This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Integrate perlio:
[perl5.git] / ext / Storable / Storable.pm
CommitLineData
25f64a11
AMS
1# $Id: Storable.pm,v 1.0.1.13 2001/12/01 13:34:49 ram Exp $
2#
3# Copyright (c) 1995-2000, Raphael Manfredi
4#
5# You may redistribute only under the same terms as Perl 5, as specified
6# in the README file that comes with the distribution.
7#
7a6a85bf
RG
8
9require DynaLoader;
10require Exporter;
11package Storable; @ISA = qw(Exporter DynaLoader);
12
13@EXPORT = qw(store retrieve);
14@EXPORT_OK = qw(
9e21b3d0 15 nstore store_fd nstore_fd fd_retrieve
7a6a85bf
RG
16 freeze nfreeze thaw
17 dclone
9e21b3d0 18 retrieve_fd
dd19458b 19 lock_store lock_nstore lock_retrieve
7a6a85bf
RG
20);
21
22use AutoLoader;
01d7b99e 23use vars qw($canonical $forgive_me $VERSION);
7a6a85bf 24
2aeb6432 25$VERSION = '2.02';
7a6a85bf
RG
26*AUTOLOAD = \&AutoLoader::AUTOLOAD; # Grrr...
27
28#
29# Use of Log::Agent is optional
30#
31
32eval "use Log::Agent";
33
530b72ba 34require Carp;
7a6a85bf 35
dd19458b
JH
36#
37# They might miss :flock in Fcntl
38#
39
40BEGIN {
596596d5 41 if (eval { require Fcntl; 1 } && exists $Fcntl::EXPORT_TAGS{'flock'}) {
dd19458b
JH
42 Fcntl->import(':flock');
43 } else {
44 eval q{
45 sub LOCK_SH () {1}
46 sub LOCK_EX () {2}
47 };
48 }
49}
50
b8778c7c 51# Can't Autoload cleanly as this clashes 8.3 with &retrieve
9e21b3d0 52sub retrieve_fd { &fd_retrieve } # Backward compatibility
cb3d9de5 53
530b72ba
NC
54# By default restricted hashes are downgraded on earlier perls.
55
56$Storable::downgrade_restricted = 1;
e8189732 57$Storable::accept_future_minor = 1;
b8778c7c
NC
58bootstrap Storable;
591;
60__END__
530b72ba
NC
61#
62# Use of Log::Agent is optional. If it hasn't imported these subs then
63# Autoloader will kindly supply our fallback implementation.
64#
65
66sub logcroak {
67 Carp::croak(@_);
68}
69
70sub logcarp {
71 Carp::carp(@_);
72}
b8778c7c 73
862382c7
JH
74#
75# Determine whether locking is possible, but only when needed.
76#
77
530b72ba 78sub CAN_FLOCK; my $CAN_FLOCK; sub CAN_FLOCK {
862382c7
JH
79 return $CAN_FLOCK if defined $CAN_FLOCK;
80 require Config; import Config;
81 return $CAN_FLOCK =
82 $Config{'d_flock'} ||
83 $Config{'d_fcntl_can_lock'} ||
84 $Config{'d_lockf'};
85}
86
0a0da639
JH
87sub show_file_magic {
88 print <<EOM;
89#
90# To recognize the data files of the Perl module Storable,
91# the following lines need to be added to the local magic(5) file,
92# usually either /usr/share/misc/magic or /etc/magic.
0a0da639
JH
93#
940 string perl-store perl Storable(v0.6) data
8b793558
JH
95>4 byte >0 (net-order %d)
96>>4 byte &01 (network-ordered)
97>>4 byte =3 (major 1)
98>>4 byte =2 (major 1)
99
0a0da639 1000 string pst0 perl Storable(v0.7) data
8b793558
JH
101>4 byte >0
102>>4 byte &01 (network-ordered)
103>>4 byte =5 (major 2)
104>>4 byte =4 (major 2)
105>>5 byte >0 (minor %d)
0a0da639
JH
106EOM
107}
108
b8778c7c
NC
109sub read_magic {
110 my $header = shift;
111 return unless defined $header and length $header > 11;
112 my $result;
113 if ($header =~ s/^perl-store//) {
114 die "Can't deal with version 0 headers";
115 } elsif ($header =~ s/^pst0//) {
116 $result->{file} = 1;
117 }
118 # Assume it's a string.
119 my ($major, $minor, $bytelen) = unpack "C3", $header;
120
121 my $net_order = $major & 1;
122 $major >>= 1;
123 @$result{qw(major minor netorder)} = ($major, $minor, $net_order);
124
125 return $result if $net_order;
126
127 # I assume that it is rare to find v1 files, so this is an intentionally
128 # inefficient way of doing it, to make the rest of the code constant.
129 if ($major < 2) {
130 delete $result->{minor};
131 $header = '.' . $header;
132 $bytelen = $minor;
133 }
134
135 @$result{qw(byteorder intsize longsize ptrsize)} =
136 unpack "x3 A$bytelen C3", $header;
137
138 if ($major >= 2 and $minor >= 2) {
139 $result->{nvsize} = unpack "x6 x$bytelen C", $header;
140 }
141 $result;
142}
7a6a85bf
RG
143
144#
145# store
146#
147# Store target object hierarchy, identified by a reference to its root.
148# The stored object tree may later be retrieved to memory via retrieve.
149# Returns undef if an I/O error occurred, in which case the file is
150# removed.
151#
152sub store {
dd19458b 153 return _store(\&pstore, @_, 0);
7a6a85bf
RG
154}
155
156#
157# nstore
158#
159# Same as store, but in network order.
160#
161sub nstore {
dd19458b
JH
162 return _store(\&net_pstore, @_, 0);
163}
164
165#
166# lock_store
167#
168# Same as store, but flock the file first (advisory locking).
169#
170sub lock_store {
171 return _store(\&pstore, @_, 1);
172}
173
174#
175# lock_nstore
176#
177# Same as nstore, but flock the file first (advisory locking).
178#
179sub lock_nstore {
180 return _store(\&net_pstore, @_, 1);
7a6a85bf
RG
181}
182
183# Internal store to file routine
184sub _store {
185 my $xsptr = shift;
186 my $self = shift;
dd19458b 187 my ($file, $use_locking) = @_;
7a6a85bf 188 logcroak "not a reference" unless ref($self);
b12202d0 189 logcroak "wrong argument number" unless @_ == 2; # No @foo in arglist
7a6a85bf 190 local *FILE;
dd19458b 191 if ($use_locking) {
6e0ac6f5 192 open(FILE, ">>$file") || logcroak "can't write into $file: $!";
862382c7 193 unless (&CAN_FLOCK) {
b29b780f
RM
194 logcarp "Storable::lock_store: fcntl/flock emulation broken on $^O";
195 return undef;
f567092b 196 }
dd19458b
JH
197 flock(FILE, LOCK_EX) ||
198 logcroak "can't get exclusive lock on $file: $!";
199 truncate FILE, 0;
200 # Unlocking will happen when FILE is closed
6e0ac6f5
JH
201 } else {
202 open(FILE, ">$file") || logcroak "can't create $file: $!";
dd19458b 203 }
6e0ac6f5 204 binmode FILE; # Archaic systems...
7a6a85bf
RG
205 my $da = $@; # Don't mess if called from exception handler
206 my $ret;
207 # Call C routine nstore or pstore, depending on network order
208 eval { $ret = &$xsptr(*FILE, $self) };
209 close(FILE) or $ret = undef;
210 unlink($file) or warn "Can't unlink $file: $!\n" if $@ || !defined $ret;
211 logcroak $@ if $@ =~ s/\.?\n$/,/;
212 $@ = $da;
213 return $ret ? $ret : undef;
214}
215
216#
217# store_fd
218#
219# Same as store, but perform on an already opened file descriptor instead.
220# Returns undef if an I/O error occurred.
221#
222sub store_fd {
223 return _store_fd(\&pstore, @_);
224}
225
226#
227# nstore_fd
228#
229# Same as store_fd, but in network order.
230#
231sub nstore_fd {
232 my ($self, $file) = @_;
233 return _store_fd(\&net_pstore, @_);
234}
235
236# Internal store routine on opened file descriptor
237sub _store_fd {
238 my $xsptr = shift;
239 my $self = shift;
240 my ($file) = @_;
241 logcroak "not a reference" unless ref($self);
242 logcroak "too many arguments" unless @_ == 1; # No @foo in arglist
243 my $fd = fileno($file);
244 logcroak "not a valid file descriptor" unless defined $fd;
245 my $da = $@; # Don't mess if called from exception handler
246 my $ret;
247 # Call C routine nstore or pstore, depending on network order
248 eval { $ret = &$xsptr($file, $self) };
249 logcroak $@ if $@ =~ s/\.?\n$/,/;
596596d5 250 local $\; print $file ''; # Autoflush the file if wanted
7a6a85bf
RG
251 $@ = $da;
252 return $ret ? $ret : undef;
253}
254
255#
256# freeze
257#
258# Store oject and its hierarchy in memory and return a scalar
259# containing the result.
260#
261sub freeze {
262 _freeze(\&mstore, @_);
263}
264
265#
266# nfreeze
267#
268# Same as freeze but in network order.
269#
270sub nfreeze {
271 _freeze(\&net_mstore, @_);
272}
273
274# Internal freeze routine
275sub _freeze {
276 my $xsptr = shift;
277 my $self = shift;
278 logcroak "not a reference" unless ref($self);
279 logcroak "too many arguments" unless @_ == 0; # No @foo in arglist
280 my $da = $@; # Don't mess if called from exception handler
281 my $ret;
282 # Call C routine mstore or net_mstore, depending on network order
283 eval { $ret = &$xsptr($self) };
284 logcroak $@ if $@ =~ s/\.?\n$/,/;
285 $@ = $da;
286 return $ret ? $ret : undef;
287}
288
289#
290# retrieve
291#
292# Retrieve object hierarchy from disk, returning a reference to the root
293# object of that tree.
294#
295sub retrieve {
dd19458b
JH
296 _retrieve($_[0], 0);
297}
298
299#
300# lock_retrieve
301#
302# Same as retrieve, but with advisory locking.
303#
304sub lock_retrieve {
305 _retrieve($_[0], 1);
306}
307
308# Internal retrieve routine
309sub _retrieve {
310 my ($file, $use_locking) = @_;
7a6a85bf 311 local *FILE;
dd19458b 312 open(FILE, $file) || logcroak "can't open $file: $!";
7a6a85bf
RG
313 binmode FILE; # Archaic systems...
314 my $self;
315 my $da = $@; # Could be from exception handler
dd19458b 316 if ($use_locking) {
862382c7 317 unless (&CAN_FLOCK) {
8be2b38b 318 logcarp "Storable::lock_store: fcntl/flock emulation broken on $^O";
b29b780f
RM
319 return undef;
320 }
8be2b38b 321 flock(FILE, LOCK_SH) || logcroak "can't get shared lock on $file: $!";
dd19458b
JH
322 # Unlocking will happen when FILE is closed
323 }
7a6a85bf
RG
324 eval { $self = pretrieve(*FILE) }; # Call C routine
325 close(FILE);
326 logcroak $@ if $@ =~ s/\.?\n$/,/;
327 $@ = $da;
328 return $self;
329}
330
331#
9e21b3d0 332# fd_retrieve
7a6a85bf
RG
333#
334# Same as retrieve, but perform from an already opened file descriptor instead.
335#
9e21b3d0 336sub fd_retrieve {
7a6a85bf
RG
337 my ($file) = @_;
338 my $fd = fileno($file);
339 logcroak "not a valid file descriptor" unless defined $fd;
340 my $self;
341 my $da = $@; # Could be from exception handler
342 eval { $self = pretrieve($file) }; # Call C routine
343 logcroak $@ if $@ =~ s/\.?\n$/,/;
344 $@ = $da;
345 return $self;
346}
347
348#
349# thaw
350#
351# Recreate objects in memory from an existing frozen image created
352# by freeze. If the frozen image passed is undef, return undef.
353#
354sub thaw {
355 my ($frozen) = @_;
356 return undef unless defined $frozen;
357 my $self;
358 my $da = $@; # Could be from exception handler
359 eval { $self = mretrieve($frozen) }; # Call C routine
360 logcroak $@ if $@ =~ s/\.?\n$/,/;
361 $@ = $da;
362 return $self;
363}
364
365=head1 NAME
366
f062ea6c 367Storable - persistence for Perl data structures
7a6a85bf
RG
368
369=head1 SYNOPSIS
370
371 use Storable;
372 store \%table, 'file';
373 $hashref = retrieve('file');
374
375 use Storable qw(nstore store_fd nstore_fd freeze thaw dclone);
376
377 # Network order
378 nstore \%table, 'file';
379 $hashref = retrieve('file'); # There is NO nretrieve()
380
381 # Storing to and retrieving from an already opened file
382 store_fd \@array, \*STDOUT;
383 nstore_fd \%table, \*STDOUT;
9e21b3d0
JH
384 $aryref = fd_retrieve(\*SOCKET);
385 $hashref = fd_retrieve(\*SOCKET);
7a6a85bf
RG
386
387 # Serializing to memory
388 $serialized = freeze \%table;
389 %table_clone = %{ thaw($serialized) };
390
391 # Deep (recursive) cloning
392 $cloneref = dclone($ref);
393
dd19458b
JH
394 # Advisory locking
395 use Storable qw(lock_store lock_nstore lock_retrieve)
396 lock_store \%table, 'file';
397 lock_nstore \%table, 'file';
398 $hashref = lock_retrieve('file');
399
7a6a85bf
RG
400=head1 DESCRIPTION
401
f062ea6c 402The Storable package brings persistence to your Perl data structures
7a6a85bf 403containing SCALAR, ARRAY, HASH or REF objects, i.e. anything that can be
c261f00e 404conveniently stored to disk and retrieved at a later time.
7a6a85bf
RG
405
406It can be used in the regular procedural way by calling C<store> with
407a reference to the object to be stored, along with the file name where
408the image should be written.
775ecd75 409
7a6a85bf
RG
410The routine returns C<undef> for I/O problems or other internal error,
411a true value otherwise. Serious errors are propagated as a C<die> exception.
412
f062ea6c
PN
413To retrieve data stored to disk, use C<retrieve> with a file name.
414The objects stored into that file are recreated into memory for you,
415and a I<reference> to the root object is returned. In case an I/O error
7a6a85bf
RG
416occurs while reading, C<undef> is returned instead. Other serious
417errors are propagated via C<die>.
418
419Since storage is performed recursively, you might want to stuff references
420to objects that share a lot of common data into a single array or hash
421table, and then store that object. That way, when you retrieve back the
422whole thing, the objects will continue to share what they originally shared.
423
424At the cost of a slight header overhead, you may store to an already
425opened file descriptor using the C<store_fd> routine, and retrieve
9e21b3d0 426from a file via C<fd_retrieve>. Those names aren't imported by default,
c261f00e 427so you will have to do that explicitly if you need those routines.
7a6a85bf
RG
428The file descriptor you supply must be already opened, for read
429if you're going to retrieve and for write if you wish to store.
430
431 store_fd(\%table, *STDOUT) || die "can't store to stdout\n";
9e21b3d0 432 $hashref = fd_retrieve(*STDIN);
7a6a85bf
RG
433
434You can also store data in network order to allow easy sharing across
435multiple platforms, or when storing on a socket known to be remotely
436connected. The routines to call have an initial C<n> prefix for I<network>,
437as in C<nstore> and C<nstore_fd>. At retrieval time, your data will be
438correctly restored so you don't have to know whether you're restoring
dd19458b
JH
439from native or network ordered data. Double values are stored stringified
440to ensure portability as well, at the slight risk of loosing some precision
441in the last decimals.
7a6a85bf 442
9e21b3d0 443When using C<fd_retrieve>, objects are retrieved in sequence, one
7a6a85bf
RG
444object (i.e. one recursive tree) per associated C<store_fd>.
445
446If you're more from the object-oriented camp, you can inherit from
447Storable and directly store your objects by invoking C<store> as
448a method. The fact that the root of the to-be-stored tree is a
449blessed reference (i.e. an object) is special-cased so that the
450retrieve does not provide a reference to that object but rather the
451blessed object reference itself. (Otherwise, you'd get a reference
452to that blessed object).
453
454=head1 MEMORY STORE
455
456The Storable engine can also store data into a Perl scalar instead, to
457later retrieve them. This is mainly used to freeze a complex structure in
458some safe compact memory place (where it can possibly be sent to another
459process via some IPC, since freezing the structure also serializes it in
460effect). Later on, and maybe somewhere else, you can thaw the Perl scalar
461out and recreate the original complex structure in memory.
462
463Surprisingly, the routines to be called are named C<freeze> and C<thaw>.
464If you wish to send out the frozen scalar to another machine, use
465C<nfreeze> instead to get a portable image.
466
467Note that freezing an object structure and immediately thawing it
468actually achieves a deep cloning of that structure:
469
470 dclone(.) = thaw(freeze(.))
471
472Storable provides you with a C<dclone> interface which does not create
473that intermediary scalar but instead freezes the structure in some
c261f00e 474internal memory space and then immediately thaws it out.
7a6a85bf 475
dd19458b
JH
476=head1 ADVISORY LOCKING
477
f062ea6c
PN
478The C<lock_store> and C<lock_nstore> routine are equivalent to
479C<store> and C<nstore>, except that they get an exclusive lock on
480the file before writing. Likewise, C<lock_retrieve> does the same
481as C<retrieve>, but also gets a shared lock on the file before reading.
dd19458b 482
f062ea6c
PN
483As with any advisory locking scheme, the protection only works if you
484systematically use C<lock_store> and C<lock_retrieve>. If one side of
485your application uses C<store> whilst the other uses C<lock_retrieve>,
dd19458b
JH
486you will get no protection at all.
487
f062ea6c
PN
488The internal advisory locking is implemented using Perl's flock()
489routine. If your system does not support any form of flock(), or if
490you share your files across NFS, you might wish to use other forms
491of locking by using modules such as LockFile::Simple which lock a
492file using a filesystem entry, instead of locking the file descriptor.
dd19458b 493
7a6a85bf
RG
494=head1 SPEED
495
496The heart of Storable is written in C for decent speed. Extra low-level
4d3295e3
PN
497optimizations have been made when manipulating perl internals, to
498sacrifice encapsulation for the benefit of greater speed.
7a6a85bf
RG
499
500=head1 CANONICAL REPRESENTATION
501
f062ea6c 502Normally, Storable stores elements of hashes in the order they are
7a6a85bf
RG
503stored internally by Perl, i.e. pseudo-randomly. If you set
504C<$Storable::canonical> to some C<TRUE> value, Storable will store
505hashes with the elements sorted by their key. This allows you to
506compare data structures by comparing their frozen representations (or
507even the compressed frozen representations), which can be useful for
508creating lookup tables for complicated queries.
509
f062ea6c 510Canonical order does not imply network order; those are two orthogonal
7a6a85bf
RG
511settings.
512
c261f00e
NC
513=head1 FORWARD COMPATIBILITY
514
515This release of Storable can be used on a newer version of Perl to
f062ea6c 516serialize data which is not supported by earlier Perls. By default,
c261f00e 517Storable will attempt to do the right thing, by C<croak()>ing if it
775ecd75 518encounters data that it cannot deserialize. However, the defaults
f062ea6c 519can be changed as follows:
c261f00e
NC
520
521=over 4
522
523=item utf8 data
524
525Perl 5.6 added support for Unicode characters with code points > 255,
526and Perl 5.8 has full support for Unicode characters in hash keys.
527Perl internally encodes strings with these characters using utf8, and
528Storable serializes them as utf8. By default, if an older version of
529Perl encounters a utf8 value it cannot represent, it will C<croak()>.
530To change this behaviour so that Storable deserializes utf8 encoded
531values as the string of bytes (effectively dropping the I<is_utf8> flag)
532set C<$Storable::drop_utf8> to some C<TRUE> value. This is a form of
533data loss, because with C<$drop_utf8> true, it becomes impossible to tell
534whether the original data was the Unicode string, or a series of bytes
535that happen to be valid utf8.
536
537=item restricted hashes
538
f062ea6c
PN
539Perl 5.8 adds support for restricted hashes, which have keys
540restricted to a given set, and can have values locked to be read only.
541By default, when Storable encounters a restricted hash on a perl
542that doesn't support them, it will deserialize it as a normal hash,
543silently discarding any placeholder keys and leaving the keys and
544all values unlocked. To make Storable C<croak()> instead, set
545C<$Storable::downgrade_restricted> to a C<FALSE> value. To restore
546the default set it back to some C<TRUE> value.
c261f00e 547
e8189732
NC
548=item files from future versions of Storable
549
550Earlier versions of Storable would immediately croak if they encountered
551a file with a higher internal version number than the reading Storable
552knew about. Internal version numbers are increased each time new data
553types (such as restricted hashes) are added to the vocabulary of the file
554format. This meant that a newer Storable module had no way of writing a
f062ea6c 555file readable by an older Storable, even if the writer didn't store newer
e8189732
NC
556data types.
557
558This version of Storable will defer croaking until it encounters a data
559type in the file that it does not recognize. This means that it will
560continue to read files generated by newer Storable modules which are careful
561in what they write out, making it easier to upgrade Storable modules in a
562mixed environment.
563
564The old behaviour of immediate croaking can be re-instated by setting
f062ea6c 565C<$Storable::accept_future_minor> to some C<FALSE> value.
e8189732 566
c261f00e
NC
567=back
568
f062ea6c 569All these variables have no effect on a newer Perl which supports the
c261f00e
NC
570relevant feature.
571
7a6a85bf
RG
572=head1 ERROR REPORTING
573
574Storable uses the "exception" paradigm, in that it does not try to workaround
575failures: if something bad happens, an exception is generated from the
576caller's perspective (see L<Carp> and C<croak()>). Use eval {} to trap
577those exceptions.
578
579When Storable croaks, it tries to report the error via the C<logcroak()>
580routine from the C<Log::Agent> package, if it is available.
581
212e9bde
JH
582Normal errors are reported by having store() or retrieve() return C<undef>.
583Such errors are usually I/O errors (or truncated stream errors at retrieval).
584
7a6a85bf
RG
585=head1 WIZARDS ONLY
586
587=head2 Hooks
588
589Any class may define hooks that will be called during the serialization
590and deserialization process on objects that are instances of that class.
591Those hooks can redefine the way serialization is performed (and therefore,
c261f00e 592how the symmetrical deserialization should be conducted).
7a6a85bf
RG
593
594Since we said earlier:
595
596 dclone(.) = thaw(freeze(.))
597
598everything we say about hooks should also hold for deep cloning. However,
599hooks get to know whether the operation is a mere serialization, or a cloning.
600
601Therefore, when serializing hooks are involved,
602
603 dclone(.) <> thaw(freeze(.))
604
605Well, you could keep them in sync, but there's no guarantee it will always
606hold on classes somebody else wrote. Besides, there is little to gain in
f062ea6c 607doing so: a serializing hook could keep only one attribute of an object,
7a6a85bf
RG
608which is probably not what should happen during a deep cloning of that
609same object.
610
611Here is the hooking interface:
612
bbc7dcd2 613=over 4
7a6a85bf
RG
614
615=item C<STORABLE_freeze> I<obj>, I<cloning>
616
617The serializing hook, called on the object during serialization. It can be
618inherited, or defined in the class itself, like any other method.
619
620Arguments: I<obj> is the object to serialize, I<cloning> is a flag indicating
621whether we're in a dclone() or a regular serialization via store() or freeze().
622
623Returned value: A LIST C<($serialized, $ref1, $ref2, ...)> where $serialized
624is the serialized form to be used, and the optional $ref1, $ref2, etc... are
625extra references that you wish to let the Storable engine serialize.
626
627At deserialization time, you will be given back the same LIST, but all the
628extra references will be pointing into the deserialized structure.
629
630The B<first time> the hook is hit in a serialization flow, you may have it
631return an empty list. That will signal the Storable engine to further
632discard that hook for this class and to therefore revert to the default
633serialization of the underlying Perl data. The hook will again be normally
634processed in the next serialization.
635
636Unless you know better, serializing hook should always say:
637
638 sub STORABLE_freeze {
639 my ($self, $cloning) = @_;
640 return if $cloning; # Regular default serialization
641 ....
642 }
643
644in order to keep reasonable dclone() semantics.
645
646=item C<STORABLE_thaw> I<obj>, I<cloning>, I<serialized>, ...
647
648The deserializing hook called on the object during deserialization.
f062ea6c 649But wait: if we're deserializing, there's no object yet... right?
7a6a85bf
RG
650
651Wrong: the Storable engine creates an empty one for you. If you know Eiffel,
652you can view C<STORABLE_thaw> as an alternate creation routine.
653
654This means the hook can be inherited like any other method, and that
655I<obj> is your blessed reference for this particular instance.
656
657The other arguments should look familiar if you know C<STORABLE_freeze>:
658I<cloning> is true when we're part of a deep clone operation, I<serialized>
659is the serialized string you returned to the engine in C<STORABLE_freeze>,
660and there may be an optional list of references, in the same order you gave
661them at serialization time, pointing to the deserialized objects (which
662have been processed courtesy of the Storable engine).
663
212e9bde
JH
664When the Storable engine does not find any C<STORABLE_thaw> hook routine,
665it tries to load the class by requiring the package dynamically (using
666the blessed package name), and then re-attempts the lookup. If at that
667time the hook cannot be located, the engine croaks. Note that this mechanism
c261f00e 668will fail if you define several classes in the same file, but L<perlmod>
212e9bde
JH
669warned you.
670
f062ea6c 671It is up to you to use this information to populate I<obj> the way you want.
7a6a85bf
RG
672
673Returned value: none.
674
675=back
676
677=head2 Predicates
678
c261f00e 679Predicates are not exportable. They must be called by explicitly prefixing
7a6a85bf
RG
680them with the Storable package name.
681
bbc7dcd2 682=over 4
7a6a85bf
RG
683
684=item C<Storable::last_op_in_netorder>
685
686The C<Storable::last_op_in_netorder()> predicate will tell you whether
687network order was used in the last store or retrieve operation. If you
688don't know how to use this, just forget about it.
689
690=item C<Storable::is_storing>
691
692Returns true if within a store operation (via STORABLE_freeze hook).
693
694=item C<Storable::is_retrieving>
695
f062ea6c 696Returns true if within a retrieve operation (via STORABLE_thaw hook).
7a6a85bf
RG
697
698=back
699
700=head2 Recursion
701
f062ea6c
PN
702With hooks comes the ability to recurse back to the Storable engine.
703Indeed, hooks are regular Perl code, and Storable is convenient when
704it comes to serializing and deserializing things, so why not use it
705to handle the serialization string?
7a6a85bf 706
f062ea6c 707There are a few things you need to know, however:
7a6a85bf 708
bbc7dcd2 709=over 4
7a6a85bf
RG
710
711=item *
712
713You can create endless loops if the things you serialize via freeze()
f062ea6c
PN
714(for instance) point back to the object we're trying to serialize in
715the hook.
7a6a85bf
RG
716
717=item *
718
719Shared references among objects will not stay shared: if we're serializing
720the list of object [A, C] where both object A and C refer to the SAME object
721B, and if there is a serializing hook in A that says freeze(B), then when
722deserializing, we'll get [A', C'] where A' refers to B', but C' refers to D,
723a deep clone of B'. The topology was not preserved.
724
725=back
726
727That's why C<STORABLE_freeze> lets you provide a list of references
728to serialize. The engine guarantees that those will be serialized in the
729same context as the other objects, and therefore that shared objects will
730stay shared.
731
732In the above [A, C] example, the C<STORABLE_freeze> hook could return:
733
734 ("something", $self->{B})
735
736and the B part would be serialized by the engine. In C<STORABLE_thaw>, you
737would get back the reference to the B' object, deserialized for you.
738
739Therefore, recursion should normally be avoided, but is nonetheless supported.
740
741=head2 Deep Cloning
742
f062ea6c 743There is a Clone module available on CPAN which implements deep cloning
7a6a85bf
RG
744natively, i.e. without freezing to memory and thawing the result. It is
745aimed to replace Storable's dclone() some day. However, it does not currently
746support Storable hooks to redefine the way deep cloning is performed.
747
0a0da639
JH
748=head1 Storable magic
749
750Yes, there's a lot of that :-) But more precisely, in UNIX systems
751there's a utility called C<file>, which recognizes data files based on
752their contents (usually their first few bytes). For this to work,
8b793558 753a certain file called F<magic> needs to taught about the I<signature>
0a0da639 754of the data. Where that configuration file lives depends on the UNIX
f062ea6c 755flavour; often it's something like F</usr/share/misc/magic> or
8b793558
JH
756F</etc/magic>. Your system administrator needs to do the updating of
757the F<magic> file. The necessary signature information is output to
f062ea6c
PN
758STDOUT by invoking Storable::show_file_magic(). Note that the GNU
759implementation of the C<file> utility, version 3.38 or later,
760is expected to contain support for recognising Storable files
761out-of-the-box, in addition to other kinds of Perl files.
0a0da639 762
7a6a85bf
RG
763=head1 EXAMPLES
764
765Here are some code samples showing a possible usage of Storable:
766
767 use Storable qw(store retrieve freeze thaw dclone);
768
769 %color = ('Blue' => 0.1, 'Red' => 0.8, 'Black' => 0, 'White' => 1);
770
771 store(\%color, '/tmp/colors') or die "Can't store %a in /tmp/colors!\n";
772
773 $colref = retrieve('/tmp/colors');
774 die "Unable to retrieve from /tmp/colors!\n" unless defined $colref;
775 printf "Blue is still %lf\n", $colref->{'Blue'};
776
777 $colref2 = dclone(\%color);
778
779 $str = freeze(\%color);
780 printf "Serialization of %%color is %d bytes long.\n", length($str);
781 $colref3 = thaw($str);
782
783which prints (on my machine):
784
785 Blue is still 0.100000
786 Serialization of %color is 102 bytes long.
787
788=head1 WARNING
789
790If you're using references as keys within your hash tables, you're bound
f062ea6c 791to be disappointed when retrieving your data. Indeed, Perl stringifies
7a6a85bf
RG
792references used as hash table keys. If you later wish to access the
793items via another reference stringification (i.e. using the same
794reference that was used for the key originally to record the value into
795the hash table), it will work because both references stringify to the
796same string.
797
6fe6778b
PN
798It won't work across a sequence of C<store> and C<retrieve> operations,
799however, because the addresses in the retrieved objects, which are
800part of the stringified references, will probably differ from the
801original addresses. The topology of your structure is preserved,
802but not hidden semantics like those.
7a6a85bf
RG
803
804On platforms where it matters, be sure to call C<binmode()> on the
805descriptors that you pass to Storable functions.
806
807Storing data canonically that contains large hashes can be
808significantly slower than storing the same data normally, as
c261f00e 809temporary arrays to hold the keys for each hash have to be allocated,
7a6a85bf
RG
810populated, sorted and freed. Some tests have shown a halving of the
811speed of storing -- the exact penalty will depend on the complexity of
812your data. There is no slowdown on retrieval.
813
814=head1 BUGS
815
f062ea6c 816You can't store GLOB, CODE, FORMLINE, etc.... If you can define
7a6a85bf
RG
817semantics for those operations, feel free to enhance Storable so that
818it can deal with them.
819
820The store functions will C<croak> if they run into such references
821unless you set C<$Storable::forgive_me> to some C<TRUE> value. In that
822case, the fatal message is turned in a warning and some
823meaningless string is stored instead.
824
825Setting C<$Storable::canonical> may not yield frozen strings that
826compare equal due to possible stringification of numbers. When the
f062ea6c 827string version of a scalar exists, it is the form stored; therefore,
7a6a85bf
RG
828if you happen to use your numbers as strings between two freezing
829operations on the same data structures, you will get different
830results.
831
dd19458b
JH
832When storing doubles in network order, their value is stored as text.
833However, you should also not expect non-numeric floating-point values
834such as infinity and "not a number" to pass successfully through a
835nstore()/retrieve() pair.
836
837As Storable neither knows nor cares about character sets (although it
838does know that characters may be more than eight bits wide), any difference
839in the interpretation of character codes between a host and a target
840system is your problem. In particular, if host and target use different
841code points to represent the characters used in the text representation
842of floating-point numbers, you will not be able be able to exchange
843floating-point data, even with nstore().
844
c261f00e
NC
845C<Storable::drop_utf8> is a blunt tool. There is no facility either to
846return B<all> strings as utf8 sequences, or to attempt to convert utf8
847data back to 8 bit and C<croak()> if the conversion fails.
848
7a6a85bf
RG
849=head1 CREDITS
850
851Thank you to (in chronological order):
852
853 Jarkko Hietaniemi <jhi@iki.fi>
854 Ulrich Pfeifer <pfeifer@charly.informatik.uni-dortmund.de>
855 Benjamin A. Holzman <bah@ecnvantage.com>
856 Andrew Ford <A.Ford@ford-mason.co.uk>
857 Gisle Aas <gisle@aas.no>
858 Jeff Gresham <gresham_jeffrey@jpmorgan.com>
859 Murray Nesbitt <murray@activestate.com>
860 Marc Lehmann <pcg@opengroup.org>
9e21b3d0
JH
861 Justin Banks <justinb@wamnet.com>
862 Jarkko Hietaniemi <jhi@iki.fi> (AGAIN, as perl 5.7.0 Pumpkin!)
dd19458b
JH
863 Salvador Ortiz Garcia <sog@msg.com.mx>
864 Dominic Dunlop <domo@computer.org>
865 Erik Haugan <erik@solbors.no>
7a6a85bf
RG
866
867for their bug reports, suggestions and contributions.
868
869Benjamin Holzman contributed the tied variable support, Andrew Ford
870contributed the canonical order for hashes, and Gisle Aas fixed
f062ea6c 871a few misunderstandings of mine regarding the perl internals,
7a6a85bf
RG
872and optimized the emission of "tags" in the output streams by
873simply counting the objects instead of tagging them (leading to
874a binary incompatibility for the Storable image starting at version
f062ea6c 8750.6--older images are, of course, still properly understood).
7a6a85bf 876Murray Nesbitt made Storable thread-safe. Marc Lehmann added overloading
f062ea6c 877and references to tied items support.
7a6a85bf 878
7a6a85bf
RG
879=head1 AUTHOR
880
0ba8809e 881Storable was written by Raphael Manfredi F<E<lt>Raphael_Manfredi@pobox.comE<gt>>
775ecd75 882Maintenance is now done by the perl5-porters F<E<lt>perl5-porters@perl.orgE<gt>>
0ba8809e
NC
883
884Please e-mail us with problems, bug fixes, comments and complaints,
885although if you have complements you should send them to Raphael.
886Please don't e-mail Raphael with problems, as he no longer works on
887Storable, and your message will be delayed while he forwards it to us.
7a6a85bf
RG
888
889=head1 SEE ALSO
890
c261f00e 891L<Clone>.
7a6a85bf
RG
892
893=cut