--- Compress-LZF/LZF.pm	2001/09/27 18:36:34	1.1
+++ Compress-LZF/LZF.pm	2013/08/25 18:13:26	1.33
@@ -1,6 +1,6 @@
 =head1 NAME
 
-Compress::LZF - extremely leight-weight Lev-Zimpel-Free compression
+Compress::LZF - extremely light-weight Lempel-Ziv-Free compression
 
 =head1 SYNOPSIS
 
@@ -15,8 +15,8 @@
    # import sfreeze, sfreeze_cref and sfreeze_c
    use Compress::LZF ':freeze';
 
-   $compressed = sfreeze_c [4,5,6];
-   $original_data = sthaw $compressed;
+   $serialized = sfreeze_c [4,5,6];
+   $original_data = sthaw $serialized;
 
 =head1 DESCRIPTION
 
@@ -25,7 +25,7 @@
 I<some> space but not at the cost of speed. It is ideal for repetitive
 data as well. The module is self-contained and very small (no large
 library to be pulled in). It is also free, so there should be no problems
-incoporating this module into commercial programs.
+incorporating this module into commercial programs.
 
 I have no idea wether any patents in any countries apply to this
 algorithm, but at the moment it is believed that it is free from any
@@ -33,19 +33,86 @@
 
 =head1 FUNCTIONS
 
-=head2 $compressed = compress $uncompressed
+=over 4
+
+=item $compressed = compress $uncompressed
+
+=item $compressed = compress_best $uncompressed
 
 Try to compress the given string as quickly and as much as possible. In
 the worst case, the string can enlarge by 1 byte, but that should be the
 absolute exception. You can expect a 45% compression ratio on large,
 binary strings.
 
-=head2 $decompressed = decompress $compressed
+The C<compress_best> function uses a different algorithm that is slower
+but usually achieves better compression.
+
+=item $decompressed = decompress $compressed
 
 Uncompress the string (compressed by C<compress>) and return the original
 data. Decompression errors can result in either broken data (there is no
 checksum kept) or a runtime error.
 
+=item $serialized = sfreeze $value (simplified freeze)
+
+=item $serialized = sfreeze_best $value
+
+Often there is the need to serialize data into a string. This function does that, by using the Storable
+module. It does the following transforms:
+
+  undef (the perl undefined value)
+     => a special cookie (undef'ness is being preserved)
+  IV, NV, PV (i.e. a _plain_ perl scalar):
+     => stays as is when it contains normal text/numbers
+     => gets serialized into a string
+  RV, undef, other funny objects (magical ones for example):
+     => data structure is freeze'd into a string.
+
+That is, it tries to leave "normal", human-readable data untouched but
+still serializes complex data structures into strings. The idea is to keep
+readability as high as possible, and in cases readability can't be helped
+anyways, it tries to compress the string.
+
+The C<sfreeze> functions will enlarge the original data one byte at most
+and will only load the Storable method when neccessary.
+
+The C<sfreeze_best> function uses a different algorithm that is slower
+but usually achieves better compression.
+
+=item $serialized = sfreeze_c $value (sfreeze and compress)
+
+=item $serialized = sfreeze_c_best $value
+
+Similar to C<sfreeze>, but always tries to C<c>ompress the resulting
+string. This still leaves most small objects (most numbers) untouched.
+
+The C<sfreeze_c> function uses a different algorithm that is slower
+but usually achieves better compression.
+
+=item $serialized = sfreeze_cr $value (sfreeze and compress references)
+
+=item $serialized = sfreeze_cr_best $value
+
+Similar to C<sfreeze>, but tries to C<c>ompress the resulting string
+unless it's a "simple" string. References for example are not "simple" and
+as such are being compressed.
+
+The C<sfreeze_cr_best> function uses a different algorithm that is slower
+but usually achieves better compression.
+
+=item $original_data = sthaw $serialized
+
+Recreate the original object from it's serialized representation. This
+function automatically detects all the different sfreeze formats.
+
+=item Compress::LZF::set_serializer $package, $freeze, $thaw
+
+Set the serialize module and functions to use. The default is "Storable",
+"Storable::net_mstore" and "Storable::mretrieve", which should be fine for
+most purposes.
+
+=back
+
 =head1 SEE ALSO
 
 Other Compress::* modules, especially Compress::LZV1 (an older, less
@@ -57,7 +124,7 @@
 =head1 AUTHOR
 
 This perl extension and the underlying liblzf were written by Marc Lehmann
-<pcg@goof.com> (See also http://liblzf.plan9.de/).
+<schmorp@schmorp.de> (See also http://liblzf.plan9.de/).
 
 =head1 BUGS
 
@@ -68,11 +135,11 @@
 require Exporter;
 require DynaLoader;
 
-$VERSION = 0.1;
+$VERSION = '3.7';
 @ISA = qw/Exporter DynaLoader/;
 %EXPORT_TAGS = (
-      freeze   => [qw(sfreeze sfreeze_cr sfreeze_c sthaw)],
-      compress => [qw(compress decompress)],
+      freeze   => [qw(sfreeze sfreeze_best sfreeze_cr sfreeze_cr_best sfreeze_c sfreeze_c_best sthaw)],
+      compress => [qw(compress compress_best decompress)],
 );
 
 Exporter::export_tags('compress');