X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=ext%2FStorable%2FStorable.pm;h=e1a72f6a83be707ab3a23fb539e804ab33a60535;hb=2cc1b180444ab1e2ac675ff3e9f78a123bc70c80;hp=0224795392ae9ebf3d7cbf7f550557639f673cbe;hpb=94b7da0e7445ac6f71b6c28e07a5f8d245133222;p=p5sagit%2Fp5-mst-13.2.git diff --git a/ext/Storable/Storable.pm b/ext/Storable/Storable.pm index 0224795..e1a72f6 100644 --- a/ext/Storable/Storable.pm +++ b/ext/Storable/Storable.pm @@ -1,58 +1,9 @@ -;# $Id: Storable.pm,v 1.0.1.13 2001/12/01 13:34:49 ram Exp $ -;# -;# Copyright (c) 1995-2000, Raphael Manfredi -;# -;# You may redistribute only under the same terms as Perl 5, as specified -;# in the README file that comes with the distribution. -;# -;# $Log: Storable.pm,v $ -;# Revision 1.0.1.13 2001/12/01 13:34:49 ram -;# patch14: avoid requiring Fcntl upfront, useful to embedded runtimes -;# patch14: store_fd() will now correctly autoflush file if needed -;# -;# Revision 1.0.1.12 2001/08/28 21:51:51 ram -;# patch13: fixed truncation race with lock_retrieve() in lock_store() -;# -;# Revision 1.0.1.11 2001/07/01 11:22:14 ram -;# patch12: systematically use "=over 4" for POD linters -;# patch12: updated version number -;# -;# 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. -;# +# +# Copyright (c) 1995-2000, Raphael Manfredi +# +# You may redistribute only under the same terms as Perl 5, as specified +# in the README file that comes with the distribution. +# require DynaLoader; require Exporter; @@ -68,9 +19,9 @@ package Storable; @ISA = qw(Exporter DynaLoader); ); use AutoLoader; -use vars qw($forgive_me $VERSION); +use vars qw($canonical $forgive_me $VERSION); -$VERSION = '2.0'; +$VERSION = '2.07'; *AUTOLOAD = \&AutoLoader::AUTOLOAD; # Grrr... # @@ -410,6 +361,9 @@ sub thaw { return $self; } +1; +__END__ + =head1 NAME Storable - persistence for Perl data structures @@ -558,6 +512,22 @@ creating lookup tables for complicated queries. Canonical order does not imply network order; those are two orthogonal settings. +=head1 CODE REFERENCES + +Since Storable version 2.05, CODE references may be serialized with +the help of L. To enable this feature, set +C<$Storable::Deparse> to a true value. To enable deserializazion, +C<$Storable::Eval> should be set to a true value. Be aware that +deserialization is done through C, which is dangerous if the +Storable file contains malicious data. You can set C<$Storable::Eval> +to a subroutine reference which would be used instead of C. See +below for an example using a L compartment for deserialization +of CODE references. + +If C<$Storable::Deparse> and/or C<$Storable::Eval> are set to false +values, then the value of C<$Storable::forgive_me> (see below) is +respected while serializing and deserializing. + =head1 FORWARD COMPATIBILITY This release of Storable can be used on a newer version of Perl to @@ -833,6 +803,28 @@ which prints (on my machine): Blue is still 0.100000 Serialization of %color is 102 bytes long. +Serialization of CODE references and deserialization in a safe +compartment: + +=for example begin + + use Storable qw(freeze thaw); + use Safe; + use strict; + my $safe = new Safe; + # because of opcodes used in "use strict": + $safe->permit(qw(:default require)); + local $Storable::Deparse = 1; + local $Storable::Eval = sub { $safe->reval($_[0]) }; + my $serialized = freeze(sub { 42 }); + my $code = thaw($serialized); + $code->() == 42; + +=for example end + +=for example_testing + is( $code->(), 42 ); + =head1 WARNING If you're using references as keys within your hash tables, you're bound @@ -861,9 +853,9 @@ your data. There is no slowdown on retrieval. =head1 BUGS -You can't store GLOB, CODE, FORMLINE, etc.... If you can define -semantics for those operations, feel free to enhance Storable so that -it can deal with them. +You can't store GLOB, FORMLINE, etc.... If you can define semantics +for those operations, feel free to enhance Storable so that it can +deal with them. The store functions will C if they run into such references unless you set C<$Storable::forgive_me> to some C value. In that @@ -894,10 +886,68 @@ C is a blunt tool. There is no facility either to return B strings as utf8 sequences, or to attempt to convert utf8 data back to 8 bit and C if the conversion fails. -In EBCDIC platforms, restoring restricted hashes (a new perl 5.8 -feature) does not work (the contents of the hashes are restored -but the read-onlyness of either the whole hash or particular -elements is lost). +Prior to Storable 2.01, no distinction was made between signed and +unsigned integers on storing. By default Storable prefers to store a +scalars string representation (if it has one) so this would only cause +problems when storing large unsigned integers that had never been coverted +to string or floating point. In other words values that had been generated +by integer operations such as logic ops and then not used in any string or +arithmetic context before storing. + +=head2 64 bit data in perl 5.6.0 and 5.6.1 + +This section only applies to you if you have existing data written out +by Storable 2.02 or earlier on perl 5.6.0 or 5.6.1 on Unix or Linux which +has been configured with 64 bit integer support (not the default) +If you got a precompiled perl, rather than running Configure to build +your own perl from source, then it almost certainly does not affect you, +and you can stop reading now (unless you're curious). If you're using perl +on Windows it does not affect you. + +Storable writes a file header which contains the sizes of various C +language types for the C compiler that built Storable (when not writing in +network order), and will refuse to load files written by a Storable not +on the same (or compatible) architecture. This check and a check on +machine byteorder is needed because the size of various fields in the file +are given by the sizes of the C language types, and so files written on +different architectures are incompatible. This is done for increased speed. +(When writing in network order, all fields are written out as standard +lengths, which allows full interworking, but takes longer to read and write) + +Perl 5.6.x introduced the ability to optional configure the perl interpreter +to use C's C type to allow scalars to store 64 bit integers on 32 +bit systems. However, due to the way the Perl configuration system +generated the C configuration files on non-Windows platforms, and the way +Storable generates its header, nothing in the Storable file header reflected +whether the perl writing was using 32 or 64 bit integers, despite the fact +that Storable was storing some data differently in the file. Hence Storable +running on perl with 64 bit integers will read the header from a file +written by a 32 bit perl, not realise that the data is actually in a subtly +incompatible format, and then go horribly wrong (possibly crashing) if it +encountered a stored integer. This is a design failure. + +Storable has now been changed to write out and read in a file header with +information about the size of integers. It's impossible to detect whether +an old file being read in was written with 32 or 64 bit integers (they have +the same header) so it's impossible to automatically switch to a correct +backwards compatibility mode. Hence this Storable defaults to the new, +correct behaviour. + +What this means is that if you have data written by Storable 1.x running +on perl 5.6.0 or 5.6.1 configured with 64 bit integers on Unix or Linux +then by default this Storable will refuse to read it, giving the error +I. If you have such data then you you +should set C<$Storable::interwork_56_64bit> to a true value to make this +Storable read and write files with the old header. You should also +migrate your data, or any older perl you are communicating with, to this +current version of Storable. + +If you don't have data written with specific configuration of perl described +above, then you do not and should not do anything. Don't set the flag - +not only will Storable on an identically configured perl refuse to load them, +but Storable a differently configured perl will load them believing them +to be correct for it, and then may well fail or crash part way through +reading them. =head1 CREDITS @@ -944,4 +994,3 @@ Storable, and your message will be delayed while he forwards it to us. L. =cut -