Change sense from "incomplete" to "implemented but needs more work" in perlunicode.pod

[p5sagit/p5-mst-13.2.git] / ext / Storable / Storable.pm

diff --git a/ext/Storable/Storable.pm b/ext/Storable/Storable.pm
index df3e946..fa15b01 100644 (file)
--- a/ext/Storable/Storable.pm
+++ b/ext/Storable/Storable.pm
@@ -1,4 +1,4 @@
-;# $Id: Storable.pm,v 1.0 2000/09/01 19:40:41 ram Exp $
+;# $Id: Storable.pm,v 1.0.1.10 2001/03/15 00:20:25 ram Exp $
 ;#
 ;#  Copyright (c) 1995-2000, Raphael Manfredi
 ;#  
@@ -6,6 +6,39 @@
 ;#  in the README file that comes with the distribution.
 ;#
 ;# $Log: Storable.pm,v $
+;# Revision 1.0.1.10  2001/03/15 00:20:25  ram
+;# patch11: updated version number
+;#
+;# Revision 1.0.1.9  2001/02/17 12:37:32  ram
+;# patch10: forgot to increase version number at previous patch
+;#
+;# Revision 1.0.1.8  2001/02/17 12:24:37  ram
+;# patch8: fixed incorrect error message
+;#
+;# Revision 1.0.1.7  2001/01/03 09:39:02  ram
+;# patch7: added CAN_FLOCK to determine whether we can flock() or not
+;#
+;# Revision 1.0.1.6  2000/11/05 17:20:25  ram
+;# patch6: increased version number
+;#
+;# Revision 1.0.1.5  2000/10/26 17:10:18  ram
+;# patch5: documented that store() and retrieve() can return undef
+;# patch5: added paragraph explaining the auto require for thaw hooks
+;#
+;# Revision 1.0.1.4  2000/10/23 18:02:57  ram
+;# patch4: protected calls to flock() for dos platform
+;# patch4: added logcarp emulation if they don't have Log::Agent
+;#
+;# Revision 1.0.1.3  2000/09/29 19:49:01  ram
+;# patch3: updated version number
+;#
+;# Revision 1.0.1.2  2000/09/28 21:42:51  ram
+;# patch2: added lock_store lock_nstore lock_retrieve
+;#
+;# Revision 1.0.1.1  2000/09/17 16:46:21  ram
+;# patch1: documented that doubles are stringified by nstore()
+;# patch1: added Salvador Ortiz Garcia in CREDITS section
+;#
 ;# Revision 1.0  2000/09/01 19:40:41  ram
 ;# Baseline for first official release.
 ;#
@@ -26,7 +59,7 @@ package Storable; @ISA = qw(Exporter DynaLoader);
 use AutoLoader;
 use vars qw($forgive_me $VERSION);
 
-$VERSION = '1.004';
+$VERSION = '1.011';
 *AUTOLOAD = \&AutoLoader::AUTOLOAD;            # Grrr...
 
 #
@@ -69,6 +102,21 @@ sub logcarp;
 
 sub retrieve_fd { &fd_retrieve }               # Backward compatibility
 
+#
+# Determine whether locking is possible, but only when needed.
+#
+
+my $CAN_FLOCK;
+
+sub CAN_FLOCK {
+       return $CAN_FLOCK if defined $CAN_FLOCK;
+       require Config; import Config;
+       return $CAN_FLOCK =
+               $Config{'d_flock'} ||
+               $Config{'d_fcntl_can_lock'} ||
+               $Config{'d_lockf'};
+}
+
 bootstrap Storable;
 1;
 __END__
@@ -118,12 +166,12 @@ sub _store {
        my $self = shift;
        my ($file, $use_locking) = @_;
        logcroak "not a reference" unless ref($self);
-       logcroak "too many arguments" unless @_ == 2;   # No @foo in arglist
+       logcroak "wrong argument number" unless @_ == 2;        # No @foo in arglist
        local *FILE;
        open(FILE, ">$file") || logcroak "can't create $file: $!";
        binmode FILE;                           # Archaic systems...
        if ($use_locking) {
-               if ($^O eq 'dos') {
+               unless (&CAN_FLOCK) {
                        logcarp "Storable::lock_store: fcntl/flock emulation broken on $^O";
                        return undef;
                }
@@ -243,7 +291,7 @@ sub _retrieve {
        my $self;
        my $da = $@;                                                    # Could be from exception handler
        if ($use_locking) {
-               if ($^O eq 'dos') {
+               unless (&CAN_FLOCK) {
                        logcarp "Storable::lock_store: fcntl/flock emulation broken on $^O";
                        return undef;
                }
@@ -448,6 +496,9 @@ those exceptions.
 When Storable croaks, it tries to report the error via the C<logcroak()>
 routine from the C<Log::Agent> package, if it is available.
 
+Normal errors are reported by having store() or retrieve() return C<undef>.
+Such errors are usually I/O errors (or truncated stream errors at retrieval).
+
 =head1 WIZARDS ONLY
 
 =head2 Hooks
@@ -476,7 +527,7 @@ same object.
 
 Here is the hooking interface:
 
-=over
+=over 4
 
 =item C<STORABLE_freeze> I<obj>, I<cloning>
 
@@ -527,6 +578,13 @@ and there may be an optional list of references, in the same order you gave
 them at serialization time, pointing to the deserialized objects (which
 have been processed courtesy of the Storable engine).
 
+When the Storable engine does not find any C<STORABLE_thaw> hook routine,
+it tries to load the class by requiring the package dynamically (using
+the blessed package name), and then re-attempts the lookup.  If at that
+time the hook cannot be located, the engine croaks.  Note that this mechanism
+will fail if you define several classes in the same file, but perlmod(1)
+warned you.
+
 It is up to you to use these information to populate I<obj> the way you want.
 
 Returned value: none.
@@ -538,7 +596,7 @@ Returned value: none.
 Predicates are not exportable.  They must be called by explicitely prefixing
 them with the Storable package name.
 
-=over
+=over 4
 
 =item C<Storable::last_op_in_netorder>
 
@@ -565,7 +623,7 @@ serialization string?
 
 There are a few things you need to know however:
 
-=over
+=over 4
 
 =item *