ext/Compress/Raw/Zlib/fallback/constants.xs Compress::Raw::Zlib
ext/Compress/Raw/Zlib/lib/Compress/Raw/Zlib.pm Compress::Raw::Zlib
ext/Compress/Raw/Zlib/Makefile.PL Compress::Raw::Zlib
+ext/Compress/Raw/Zlib/pod/FAQ.pod Compress::Raw::Zlib
ext/Compress/Raw/Zlib/private/MakeUtil.pm Compress::Raw::Zlib
ext/Compress/Raw/Zlib/README Compress::Raw::Zlib
ext/Compress/Raw/Zlib/t/01version.t Compress::Raw::Zlib
ext/Compress/Zlib/examples/gzstream Compress::Zlib
ext/Compress/Zlib/lib/Compress/Zlib.pm Compress::Zlib
ext/Compress/Zlib/Makefile.PL Compress::Zlib
+ext/Compress/Zlib/pod/FAQ.pod Compress::Zlib
ext/Compress/Zlib/private/MakeUtil.pm Compress::Zlib
ext/Compress/Zlib/README Compress::Zlib
ext/Compress/Zlib/t/01version.t Compress::Zlib
ext/IO_Compress_Base/lib/IO/Uncompress/AnyUncompress.pm IO::Compress::Base
ext/IO_Compress_Base/lib/IO/Uncompress/Base.pm IO::Compress::Base
ext/IO_Compress_Base/Makefile.PL IO::Compress::Base
+ext/IO_Compress_Base/pod/FAQ.pod IO::Compress::Base
ext/IO_Compress_Base/private/MakeUtil.pm IO::Compress::Base
ext/IO_Compress_Base/README IO::Compress::Base
ext/IO_Compress_Base/t/01misc.t IO::Compress::Base
ext/IO_Compress_Zlib/lib/IO/Uncompress/RawInflate.pm IO::Compress::Zlib
ext/IO_Compress_Zlib/lib/IO/Uncompress/Unzip.pm IO::Compress::Zlib
ext/IO_Compress_Zlib/Makefile.PL IO::Compress::Zlib
+ext/IO_Compress_Zlib/pod/FAQ.pod IO::Compress::Zlib
ext/IO_Compress_Zlib/private/MakeUtil.pm IO::Compress::Zlib
ext/IO_Compress_Zlib/README IO::Compress::Zlib
ext/IO_Compress_Zlib/t/001zlib-generic-deflate.t IO::Compress::Zlib
CHANGES
-------
+ 2.009 20 April 2008
+
+ * No Changes
+
2.008 2 November 2007
* Minor documentation changes in README
Compress-Raw-Zlib
- Version 2.008
+ Version 2.009
- 2nd November 2007
+ 20th April 2008
-
- Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
+ Copyright (c) 2005-2008 Paul Marquess. All rights reserved.
This program is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.
-
The directory zlib-src contains a subset of the
source files copied directly from zlib version 1.2.3.
These files are Copyright(C) 1995-2005
Full source for the zlib library is available at
http://www.zlib.org
-
-
DESCRIPTION
-----------
-
This module provides a Perl interface to the zlib compression library.
-
-
-
-
PREREQUISITES
-------------
Before you can build Compress-Raw-Zlib you need to have the following
installed on your system:
-
* A C compiler
* Perl 5.004 or better.
-
-
By default, Compress-Raw-Zlib will build its own private copy of the
zlib library. If you want to use a different version of
zlib, follow the instructions in the section called
"Controlling the version of zlib used by Compress-Raw-Zlib"
later in this document.
-
-
BUILDING THE MODULE
-------------------
make
make test
-
-
INSTALLATION
------------
make install
-
-
-
Controlling the version of zlib used by Compress-Raw-Zlib
----------------------------------------------------------
Note that if you intend to use either Option 2 or 3, you need to have
zlib version 1.0.5 or better.
-
The contents of the file config.in are used to control which of the
three options is actually used. This file is read during the
step of the build, so remember to make any required changes to config.in
before building this module.
-
-
Option 1
--------
------------------------
Every gzip stream stores a byte in its header to identify the Operating
-System that was used to create the gzip stream. When you build
-Compress-Raw-Zlib it will attempt to determine the value that is correct for
-your Operating System. This will then be used by IO::Gzip as the default
-value for the OS byte in all gzip headers it creates.
+System that was used to create the gzip stream. When you build Compress-Raw-Zlib it will attempt to determine the value that is correct for
+your Operating System. This will then be used by IO::Compress::Gzip as the
+default value for the OS byte in all gzip headers it creates.
The variable GZIP_OS_CODE in the config.in file controls the setting of
this value when building Compress-Raw-Zlib. If GZIP_OS_CODE is set to
detected is incorrect, please take a few moments to contact the author of
this module.
-
-
TROUBLESHOOTING
---------------
-
-
-
-
-
-
Solaris build fails with "language optional software package not installed"
---------------------------------------------------------------------------
If that doesn't work for you, it's time to make changes to the Makefile
by hand. Good luck!
-
-
-
Solaris build fails with "gcc: unrecognized option `-KPIC'"
-----------------------------------------------------------
is necessary to have first built the zlib library with the -fpic
option.
-
-
-
-
Linux Notes
-----------
for zlib. Check for an RPM that start with "zlib-devel" in your Linux
distribution.
-
-
-
Win32 Notes
-----------
C:\> ppm verify -upgrade Compress-Zlib
-
If you are not running Activestate Perl and you don't have access
to a C compiler, you will not be able to build and install this module.
-
-
-
Win32 & Cygwin Notes
--------------------
The workaround is to install Compress-Raw-Zlib manually using the
instructions given at the start of this file.
-
FEEDBACK
--------
If you haven't installed Compress-Raw-Zlib then search Compress::Raw::Zlib.pm
for a line like this:
- $VERSION = "2.008" ;
-
+ $VERSION = "2.009" ;
c. The version of zlib you have used.
If you have successfully installed Compress-Raw-Zlib, this one-liner
perl -MCompress::Raw::Zlib -e "print q[zlib ver ]. Compress::Raw::Zlib::ZLIB_VERSION.qq[\n]"
-
If not, look at the beginning of the file zlib.h.
-
2. If you are having problems building Compress-Raw-Zlib, send me a
complete log of what happened. Start by unpacking the Compress-Raw-Zlib
module into a fresh directory and keep a log of all the steps
make
make test TEST_VERBOSE=1
-
Paul Marquess <pmqs@cpan.org>
#define adlerInitial adler32(0L, Z_NULL, 0)
#define crcInitial crc32(0L, Z_NULL, 0)
-static const char * const my_z_errmsg[] = {
+//static const char * const my_z_errmsg[] = {
+static const char my_z_errmsg[][32] = {
"need dictionary", /* Z_NEED_DICT 2 */
"stream end", /* Z_STREAM_END 1 */
"", /* Z_OK 0 */
use bytes ;
our ($VERSION, $XS_VERSION, @ISA, @EXPORT, $AUTOLOAD);
-$VERSION = '2.008';
+$VERSION = '2.009';
$XS_VERSION = $VERSION;
$VERSION = eval $VERSION;
compression library (see L</AUTHOR> for details about where to get
I<zlib>).
-
-
=head1 Compress::Raw::Zlib::Deflate
This section defines an interface that allows in-memory compression using
Here is a definition of the interface available:
-
=head2 B<($d, $status) = new Compress::Raw::Zlib::Deflate( [OPT] ) >
Initialises a deflation object.
This option defaults to false.
-
=item B<-ADLER32>
If set to true, an adler32 checksum of the uncompressed data will be
This option defaults to false.
-
=back
Here is an example of using the C<Compress::Raw::Zlib::Deflate> optional
my $d = new Compress::Raw::Zlib::Deflate ( -Bufsize => 300,
-Level => Z_BEST_SPEED ) ;
-
=head2 B<$status = $d-E<gt>deflate($input, $output)>
Deflates the contents of C<$input> and writes the compressed data to
The list of the valid options is shown below. Options not specified
will remain unchanged.
-
=over 5
=item B<-Level>
reallocated to increase the size, it will grow in increments of
C<Bufsize>.
-
=back
=head2 B<$status = $d-E<gt>deflateTune($good_length, $max_lazy, $nice_length, $max_chain)>
Returns the deflation strategy currently used. Valid values are
C<Z_DEFAULT_STRATEGY>, C<Z_FILTERED> and C<Z_HUFFMAN_ONLY>.
-
=head2 B<$d-E<gt>get_Level()>
Returns the compression level being used.
=head2 Example
-
Here is a trivial example of using C<deflate>. It simply reads standard
input, deflates it and writes it to standard output.
Here is a definition of the interface:
-
=head2 B< ($i, $status) = new Compress::Raw::Zlib::Inflate( [OPT] ) >
Initialises an inflation object.
This option defaults to false.
-
=item B<-CRC32>
If set to true, a crc32 checksum of the uncompressed data will be
data streams. They must have been added explicitly when the data stream
was created by calling C<Compress::Deflate::flush> with C<Z_FULL_FLUSH>.
-
=head2 B<$i-E<gt>dict_adler()>
Returns the adler32 value for the dictionary.
http://www.cpan.org/modules/by-module/Archive/Archive-Zip-*.tar.gz
-
=head1 CONSTANTS
All the I<zlib> constants are automatically imported when you make use
of I<Compress::Raw::Zlib>.
-
=head1 SEE ALSO
L<Compress::Zlib>, L<IO::Compress::Gzip>, L<IO::Uncompress::Gunzip>, L<IO::Compress::Deflate>, L<IO::Uncompress::Inflate>, L<IO::Compress::RawDeflate>, L<IO::Uncompress::RawInflate>, L<IO::Compress::Bzip2>, L<IO::Uncompress::Bunzip2>, L<IO::Compress::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
L<Archive::Tar|Archive::Tar>,
L<IO::Zlib|IO::Zlib>
-
For RFC 1950, 1951 and 1952 see
F<http://www.faqs.org/rfcs/rfc1950.html>,
F<http://www.faqs.org/rfcs/rfc1951.html> and
The primary site for gzip is F<http://www.gzip.org>.
-
-
-
=head1 AUTHOR
This module was written by Paul Marquess, F<pmqs@cpan.org>.
-
-
=head1 MODIFICATION HISTORY
See the Changes file.
=head1 COPYRIGHT AND LICENSE
-Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
+Copyright (c) 2005-2008 Paul Marquess. All rights reserved.
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
-
-
--- /dev/null
+
+=head1 NAME
+
+Compress::Raw::Zlib::FAQ -- Frequently Asked Questions about Compress::Raw::Zlib
+
+=head1 DESCRIPTION
+
+Common questions answered.
+
+=head2 Compatibility with Unix compress/uncompress.
+
+This module is not compatible with Unix C<compress>.
+
+If you have the C<uncompress> program available, you can use this to read
+compressed files
+
+ open F, "uncompress -c $filename |";
+ while (<F>)
+ {
+ ...
+
+Alternatively, if you have the C<gunzip> program available, you can use
+this to read compressed files
+
+ open F, "gunzip -c $filename |";
+ while (<F>)
+ {
+ ...
+
+and this to write compress files, if you have the C<compress> program
+available
+
+ open F, "| compress -c $filename ";
+ print F "data";
+ ...
+ close F ;
+
+=head2 Accessing .tar.Z files
+
+See previous FAQ item.
+
+If the C<Archive::Tar> module is installed and either the C<uncompress> or
+C<gunzip> programs are available, you can use one of these workarounds to
+read C<.tar.Z> files.
+
+Firstly with C<uncompress>
+
+ use strict;
+ use warnings;
+ use Archive::Tar;
+
+ open F, "uncompress -c $filename |";
+ my $tar = Archive::Tar->new(*F);
+ ...
+
+and this with C<gunzip>
+
+ use strict;
+ use warnings;
+ use Archive::Tar;
+
+ open F, "gunzip -c $filename |";
+ my $tar = Archive::Tar->new(*F);
+ ...
+
+Similarly, if the C<compress> program is available, you can use this to
+write a C<.tar.Z> file
+
+ use strict;
+ use warnings;
+ use Archive::Tar;
+ use IO::File;
+
+ my $fh = new IO::File "| compress -c >$filename";
+ my $tar = Archive::Tar->new();
+ ...
+ $tar->write($fh);
+ $fh->close ;
+
+=head2 Accessing Zip Files
+
+This module does not support reading/writing zip files.
+
+Support for reading/writing zip files is included with the
+C<IO::Compress::Zip> and C<IO::Uncompress::Unzip> modules.
+
+The primary focus of the C<IO::Compress::Zip> and C<IO::Uncompress::Unzip>
+modules is to provide an C<IO::File> compatible streaming read/write
+interface to zip files/buffers. They are not fully flegged archivers. If
+you are looking for an archiver check out the C<Archive::Zip> module. You
+can find it on CPAN at
+
+ http://www.cpan.org/modules/by-module/Archive/Archive-Zip-*.tar.gz
+
+=head2 Zlib Library Version Support
+
+By default C<Compress::Raw::Zlib> will build with a private copy of version
+1.2.3 of the zlib library. (See the F<README> file for details of
+how to override this behaviour)
+
+If you decide to use a different version of the zlib library, you need to be
+aware of the following issues
+
+=over 5
+
+=item *
+
+First off, you must have zlib 1.0.5 or better.
+
+=item *
+
+You need to have zlib 1.2.1 or better if you want to use the C<-Merge>
+option with C<IO::Compress::Gzip>, C<IO::Compress::Deflate> and
+C<IO::Compress::RawDeflate>.
+
+=back
+
+=head1 SEE ALSO
+
+L<Compress::Zlib>, L<IO::Compress::Gzip>, L<IO::Uncompress::Gunzip>, L<IO::Compress::Deflate>, L<IO::Uncompress::Inflate>, L<IO::Compress::RawDeflate>, L<IO::Uncompress::RawInflate>, L<IO::Compress::Bzip2>, L<IO::Uncompress::Bunzip2>, L<IO::Compress::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
+
+L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
+
+L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
+L<Archive::Tar|Archive::Tar>,
+L<IO::Zlib|IO::Zlib>
+
+=head1 AUTHOR
+
+This module was written by Paul Marquess, F<pmqs@cpan.org>.
+
+=head1 MODIFICATION HISTORY
+
+See the Changes file.
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright (c) 2005-2008 Paul Marquess. All rights reserved.
+
+This program is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+
CHANGES
-------
+ 2.009 20 April 2008
+
+ * Minor documentation issue with flush.
+ [rt.cpan.org #31446]
+
2.008 2 November 2007
* Minor documentation changes in README
use strict ;
require 5.004 ;
-$::VERSION = '2.008' ;
+$::VERSION = '2.009' ;
use private::MakeUtil;
use ExtUtils::MakeMaker 5.16 ;
Compress-Zlib
- Version 2.008
+ Version 2.009
- 2nd November 2007
+ 20th April 2008
-
- Copyright (c) 1995-2007 Paul Marquess. All rights reserved.
+ Copyright (c) 1995-2008 Paul Marquess. All rights reserved.
This program is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.
-
-
-
DESCRIPTION
-----------
-
This module provides a Perl interface to the zlib compression library.
-
-
-
-
PREREQUISITES
-------------
Before you can build Compress-Zlib you need to have the following
installed on your system:
-
* Perl 5.004 or better.
* Compress::Raw::Zlib
* IO::Compress::Gzip
-
-
-
-
BUILDING THE MODULE
-------------------
make
make test
-
-
INSTALLATION
------------
make install
-
-
-
-
TROUBLESHOOTING
---------------
-
Undefined Symbol gzsetparams
----------------------------
2. Edit config.in and set the OLD_ZLIB variable to True.
-
-
Test Harness 01version fails
----------------------------
If the 01version test harness fails, and the problem isn't covered by the
Try removing the one you don't want to use and rebuild.
-
-
-
-
-
-
-
-
FEEDBACK
--------
If you haven't installed Compress-Zlib then search Compress::Zlib.pm
for a line like this:
- $VERSION = "2.008" ;
-
-
+ $VERSION = "2.009" ;
2. If you are having problems building Compress-Zlib, send me a
complete log of what happened. Start by unpacking the Compress-Zlib
make
make test TEST_VERBOSE=1
-
Paul Marquess <pmqs@cpan.org>
use IO::Handle ;
use Scalar::Util qw(dualvar);
-use IO::Compress::Base::Common 2.008 ;
-use Compress::Raw::Zlib 2.008 ;
-use IO::Compress::Gzip 2.008 ;
-use IO::Uncompress::Gunzip 2.008 ;
+use IO::Compress::Base::Common 2.009 ;
+use Compress::Raw::Zlib 2.009 ;
+use IO::Compress::Gzip 2.009 ;
+use IO::Uncompress::Gunzip 2.009 ;
use strict ;
use warnings ;
use bytes ;
our ($VERSION, $XS_VERSION, @ISA, @EXPORT, $AUTOLOAD);
-$VERSION = '2.008';
+$VERSION = '2.009';
$XS_VERSION = $VERSION;
$VERSION = eval $VERSION;
package Compress::Zlib ;
-use IO::Compress::Gzip::Constants 2.008 ;
+use IO::Compress::Gzip::Constants 2.009 ;
sub memGzip($)
{
($d, $status) = deflateInit( [OPT] ) ;
$status = $d->deflate($input, $output) ;
- $status = $d->flush($output [, $flush_type]) ;
+ $status = $d->flush([$flush_type]) ;
$d->deflateParams(OPTS) ;
$d->deflateTune(OPTS) ;
$d->dict_adler() ;
ZLIB_VERSION
ZLIB_VERNUM
-
-
=head1 DESCRIPTION
The I<Compress::Zlib> module provides a Perl interface to the I<zlib>
Returns 0 on success.
-
=item B<$offset = $gz-E<gt>gztell() ;>
Returns the uncompressed file offset.
=back
-
=head2 Examples
Here is an example script which uses the interface. It implements a
C<Z_BEST_COMPRESSION>, and C<Z_DEFAULT_COMPRESSION>.
If C<$level> is not specified C<Z_DEFAULT_COMPRESSION> will be used.
-
=item B<$dest = uncompress($source) ;>
Uncompresses C<$source>. If successful it returns the uncompressed
this distribution for an alternative interface for reading/writing RFC 1950
files/buffers.
-
=head1 Deflate Interface
This section defines an interface that allows in-memory compression using
Here is a definition of the interface available:
-
=head2 B<($d, $status) = deflateInit( [OPT] )>
Initialises a deflation stream.
deflateInit( -Bufsize => 300,
-Level => Z_BEST_SPEED ) ;
-
=head2 B<($out, $status) = $d-E<gt>deflate($buffer)>
-
Deflates the contents of C<$buffer>. The buffer can either be a scalar
or a scalar reference. When finished, C<$buffer> will be
completely processed (assuming there were no errors). If the deflation
case that any output will be produced by this method. So don't rely on
the fact that C<$out> is empty for an error test.
-
-=head2 B<($out, $status) = $d-E<gt>flush([flush_type])>
+=head2 B<($out, $status) = $d-E<gt>flush()>
+=head2 B<($out, $status) = $d-E<gt>flush($flush_type)>
Typically used to finish the deflation. Any pending output will be
returned via C<$out>.
=head2 Example
-
Here is a trivial example of using C<deflate>. It simply reads standard
input, deflates it and writes it to standard output.
Here is a definition of the interface:
-
=head2 B<($i, $status) = inflateInit()>
Initialises an inflation stream.
data is available, C<inflateSync> can be called repeatedly with more
compressed data until the flush point is found.
-
=head2 B<$i-E<gt>dict_adler()>
Returns the adler32 value for the dictionary.
All the I<zlib> constants are automatically imported when you make use
of I<Compress::Zlib>.
-
=head1 SEE ALSO
L<IO::Compress::Gzip>, L<IO::Uncompress::Gunzip>, L<IO::Compress::Deflate>, L<IO::Uncompress::Inflate>, L<IO::Compress::RawDeflate>, L<IO::Uncompress::RawInflate>, L<IO::Compress::Bzip2>, L<IO::Uncompress::Bunzip2>, L<IO::Compress::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
L<Archive::Tar|Archive::Tar>,
L<IO::Zlib|IO::Zlib>
-
For RFC 1950, 1951 and 1952 see
F<http://www.faqs.org/rfcs/rfc1950.html>,
F<http://www.faqs.org/rfcs/rfc1951.html> and
The primary site for gzip is F<http://www.gzip.org>.
-
-
-
=head1 AUTHOR
This module was written by Paul Marquess, F<pmqs@cpan.org>.
-
-
=head1 MODIFICATION HISTORY
See the Changes file.
=head1 COPYRIGHT AND LICENSE
-Copyright (c) 1995-2007 Paul Marquess. All rights reserved.
+Copyright (c) 1995-2008 Paul Marquess. All rights reserved.
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
-
-
--- /dev/null
+
+=head1 NAME
+
+Compress::Zlib::FAQ -- Frequently Asked Questions about Compress::Zlib
+
+=head1 DESCRIPTION
+
+Common questions answered.
+
+=head2 Compatibility with Unix compress/uncompress.
+
+Although C<Compress::Zlib> has a pair of functions called C<compress> and
+C<uncompress>, they are I<not> related to the Unix programs of the same
+name. The C<Compress::Zlib> module is not compatible with Unix
+C<compress>.
+
+If you have the C<uncompress> program available, you can use this to read
+compressed files
+
+ open F, "uncompress -c $filename |";
+ while (<F>)
+ {
+ ...
+
+Alternatively, if you have the C<gunzip> program available, you can use
+this to read compressed files
+
+ open F, "gunzip -c $filename |";
+ while (<F>)
+ {
+ ...
+
+and this to write compress files, if you have the C<compress> program
+available
+
+ open F, "| compress -c $filename ";
+ print F "data";
+ ...
+ close F ;
+
+=head2 Accessing .tar.Z files
+
+The C<Archive::Tar> module can optionally use C<Compress::Zlib> (via the
+C<IO::Zlib> module) to access tar files that have been compressed with
+C<gzip>. Unfortunately tar files compressed with the Unix C<compress>
+utility cannot be read by C<Compress::Zlib> and so cannot be directly
+accessed by C<Archive::Tar>.
+
+If the C<uncompress> or C<gunzip> programs are available, you can use one
+of these workarounds to read C<.tar.Z> files from C<Archive::Tar>
+
+Firstly with C<uncompress>
+
+ use strict;
+ use warnings;
+ use Archive::Tar;
+
+ open F, "uncompress -c $filename |";
+ my $tar = Archive::Tar->new(*F);
+ ...
+
+and this with C<gunzip>
+
+ use strict;
+ use warnings;
+ use Archive::Tar;
+
+ open F, "gunzip -c $filename |";
+ my $tar = Archive::Tar->new(*F);
+ ...
+
+Similarly, if the C<compress> program is available, you can use this to
+write a C<.tar.Z> file
+
+ use strict;
+ use warnings;
+ use Archive::Tar;
+ use IO::File;
+
+ my $fh = new IO::File "| compress -c >$filename";
+ my $tar = Archive::Tar->new();
+ ...
+ $tar->write($fh);
+ $fh->close ;
+
+=head2 Accessing Zip Files
+
+This module does not support reading/writing zip files.
+
+Support for reading/writing zip files is included with the
+C<IO::Compress::Zip> and C<IO::Uncompress::Unzip> modules.
+
+The primary focus of the C<IO::Compress::Zip> and C<IO::Uncompress::Unzip>
+modules is to provide an C<IO::File> compatible streaming read/write
+interface to zip files/buffers. They are not fully flegged archivers. If
+you are looking for an archiver check out the C<Archive::Zip> module. You
+can find it on CPAN at
+
+ http://www.cpan.org/modules/by-module/Archive/Archive-Zip-*.tar.gz
+
+=head1 SEE ALSO
+
+L<Compress::Zlib>, L<IO::Compress::Gzip>, L<IO::Uncompress::Gunzip>, L<IO::Compress::Deflate>, L<IO::Uncompress::Inflate>, L<IO::Compress::RawDeflate>, L<IO::Uncompress::RawInflate>, L<IO::Compress::Bzip2>, L<IO::Uncompress::Bunzip2>, L<IO::Compress::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
+
+L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
+
+L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
+L<Archive::Tar|Archive::Tar>,
+L<IO::Zlib|IO::Zlib>
+
+=head1 AUTHOR
+
+This module was written by Paul Marquess, F<pmqs@cpan.org>.
+
+=head1 MODIFICATION HISTORY
+
+See the Changes file.
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright (c) 2005-2008 Paul Marquess. All rights reserved.
+
+This program is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+
CHANGES
-------
+ 2.009 20 April 2008
+
+ * Removed the alpha status from File::GlobMapper
+
+ * IO::Compress::Base
+ When writing output never output a zero length buffer.
+ Done to improve interoperability with other tied filenandle
+ modules.
+
+ * Changed IO::Uncompress::Base to not use the offset parameter of
+ the read method when reading from a filehandle.
+
+ The object returned from Net::FTP::retr implements a non-standard
+ read method. The third parameter is used for a timeout value
+ rather than an offset.
+ [rt.cpan#33231]
+
+ * Changed IO::Uncompress::Base to not use the eof method when
+ reading from a filehandle.
+
+ The object returned from Net::FTP::retr implements both the read
+ method and the eof method. Unfortunately the implementation of
+ the read method uses non-buffered IO (by using sysread) while
+ the eof method uses buffered IO. Mixing buffered and non-buffered
+ IO results in data corruption.
+
2.008 2 November 2007
* Minor documentation changes in README
IO-Compress-Base
- Version 2.008
+ Version 2.009
- 2nd November 2007
+ 20th April 2008
-
- Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
+ Copyright (c) 2005-2008 Paul Marquess. All rights reserved.
This program is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.
-
-
-
DESCRIPTION
-----------
-
This module is the base class for all IO::Compress and IO::Uncompress
modules.
-
-
-
-
PREREQUISITES
-------------
Before you can build IO-Compress-Base you need to have the following
installed on your system:
-
* Perl 5.004 or better.
-
-
-
-
BUILDING THE MODULE
-------------------
make
make test
-
-
INSTALLATION
------------
make install
-
-
-
-
TROUBLESHOOTING
---------------
-
-
-
-
-
-
-
-
-
-
-
FEEDBACK
--------
If you haven't installed IO-Compress-Base then search IO::Compress::Base.pm
for a line like this:
- $VERSION = "2.008" ;
-
-
+ $VERSION = "2.009" ;
2. If you are having problems building IO-Compress-Base, send me a
complete log of what happened. Start by unpacking the IO-Compress-Base
make
make test TEST_VERBOSE=1
-
Paul Marquess <pmqs@cpan.org>
our ($Error);
our ($VERSION, @EXPORT_OK);
-$VERSION = '0.000_02';
+$VERSION = '1.000';
@EXPORT_OK = qw( globmap );
=head1 DESCRIPTION
-B<WARNING Alpha Release Alert!>
-
-=over 5
-
-=item * This code is a work in progress.
-
-=item * There are known bugs.
-
-=item * The interface defined here is tentative.
-
-=item * There are portability issues.
-
-=item * Do not use in production code.
-
-=item * Consider yourself warned!
-
-=back
-
This module needs Perl5.005 or better.
This module takes the existing C<File::Glob> module as a starting point and
use strict ;
use warnings;
-use IO::Compress::Base::Common 2.008 ;
+use IO::Compress::Base::Common 2.009 ;
use IO::File ;
use Scalar::Util qw(blessed readonly);
our (@ISA, $VERSION);
@ISA = qw(Exporter IO::File);
-$VERSION = '2.008';
+$VERSION = '2.009';
#Can't locate object method "SWASHNEW" via package "utf8" (perhaps you forgot to load "utf8"?) at .../ext/Compress-Zlib/Gzip/blib/lib/Compress/Zlib/Common.pm line 16.
&{ *$self->{FilterEnvelope} }();
}
- if ( defined *$self->{FH} ) {
- defined *$self->{FH}->write( $data, length $data )
- or return $self->saveErrorString(0, $!, $!);
- }
- else {
- ${ *$self->{Buffer} } .= $data ;
+ if (length $data) {
+ if ( defined *$self->{FH} ) {
+ defined *$self->{FH}->write( $data, length $data )
+ or return $self->saveErrorString(0, $!, $!);
+ }
+ else {
+ ${ *$self->{Buffer} } .= $data ;
+ }
}
return 1;
=head1 NAME
-
IO::Compress::Base - Base Class for IO::Compress modules
-
=head1 SYNOPSIS
use IO::Compress::Base ;
=head1 DESCRIPTION
-
This module is not intended for direct use in application code. Its sole
purpose if to to be sub-classed by IO::Compress modules.
-
-
-
=head1 SEE ALSO
L<Compress::Zlib>, L<IO::Compress::Gzip>, L<IO::Uncompress::Gunzip>, L<IO::Compress::Deflate>, L<IO::Uncompress::Inflate>, L<IO::Compress::RawDeflate>, L<IO::Uncompress::RawInflate>, L<IO::Compress::Bzip2>, L<IO::Uncompress::Bunzip2>, L<IO::Compress::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
L<Archive::Tar|Archive::Tar>,
L<IO::Zlib|IO::Zlib>
-
-
-
-
=head1 AUTHOR
This module was written by Paul Marquess, F<pmqs@cpan.org>.
-
-
=head1 MODIFICATION HISTORY
See the Changes file.
=head1 COPYRIGHT AND LICENSE
-Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
+Copyright (c) 2005-2008 Paul Marquess. All rights reserved.
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
-
require Exporter;
our ($VERSION, @ISA, @EXPORT, %EXPORT_TAGS, $HAS_ENCODE);
@ISA = qw(Exporter);
-$VERSION = '2.008';
+$VERSION = '2.009';
@EXPORT = qw( isaFilehandle isaFilename whatIsInput whatIsOutput
isaFileGlobString cleanFileGlobString oneTarget
}
elsif (@_ == 1) {
my $href = $_[0] ;
+ return $_[0]
+ if UNIVERSAL::isa($_[0], "IO::Compress::Base::Parameters");
+
return $self->setError("Expected even number of parameters, got 1")
if ! defined $href or ! ref $href or ref $href ne "HASH" ;
use warnings;
use bytes;
-use IO::Compress::Base::Common 2.008 qw(createSelfTiedObject);
+use IO::Compress::Base::Common 2.009 qw(createSelfTiedObject);
-use IO::Uncompress::Base 2.008 ;
+use IO::Uncompress::Base 2.009 ;
require Exporter ;
our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $AnyUncompressError);
-$VERSION = '2.008';
+$VERSION = '2.009';
$AnyUncompressError = '';
@ISA = qw( Exporter IO::Uncompress::Base );
BEGIN
{
- eval ' use IO::Uncompress::Adapter::Inflate 2.008 ;';
- eval ' use IO::Uncompress::Adapter::Bunzip2 2.008 ;';
- eval ' use IO::Uncompress::Adapter::LZO 2.008 ;';
- eval ' use IO::Uncompress::Adapter::Lzf 2.008 ;';
-
- eval ' use IO::Uncompress::Bunzip2 2.008 ;';
- eval ' use IO::Uncompress::UnLzop 2.008 ;';
- eval ' use IO::Uncompress::Gunzip 2.008 ;';
- eval ' use IO::Uncompress::Inflate 2.008 ;';
- eval ' use IO::Uncompress::RawInflate 2.008 ;';
- eval ' use IO::Uncompress::Unzip 2.008 ;';
- eval ' use IO::Uncompress::UnLzf 2.008 ;';
+ eval ' use IO::Uncompress::Adapter::Inflate 2.009 ;';
+ eval ' use IO::Uncompress::Adapter::Bunzip2 2.009 ;';
+ eval ' use IO::Uncompress::Adapter::LZO 2.009 ;';
+ eval ' use IO::Uncompress::Adapter::Lzf 2.009 ;';
+
+ eval ' use IO::Uncompress::Bunzip2 2.009 ;';
+ eval ' use IO::Uncompress::UnLzop 2.009 ;';
+ eval ' use IO::Uncompress::Gunzip 2.009 ;';
+ eval ' use IO::Uncompress::Inflate 2.009 ;';
+ eval ' use IO::Uncompress::RawInflate 2.009 ;';
+ eval ' use IO::Uncompress::Unzip 2.009 ;';
+ eval ' use IO::Uncompress::UnLzf 2.009 ;';
}
sub new
sub getExtraParams
{
- use IO::Compress::Base::Common 2.008 qw(:Parse);
+ use IO::Compress::Base::Common 2.009 qw(:Parse);
return ( 'RawInflate' => [1, 1, Parse_boolean, 0] ) ;
}
=head1 NAME
-
IO::Uncompress::AnyUncompress - Uncompress gzip, zip, bzip2 or lzop file/buffer
-
=head1 SYNOPSIS
use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
eof($z)
close($z)
-
=head1 DESCRIPTION
-
This module provides a Perl interface that allows the reading of
files/buffers that have been compressed with a variety of compression
libraries.
The module will auto-detect which, if any, of the supported
compression formats is being used.
-
-
-
=head1 Functional Interface
A top-level function, C<anyuncompress>, is provided to carry out
anyuncompress $input => $output [,OPTS]
or die "anyuncompress failed: $AnyUncompressError\n";
-
-
The functional interface needs Perl5.005 or better.
-
=head2 anyuncompress $input => $output [, OPTS]
-
C<anyuncompress> expects at least two parameters, C<$input> and C<$output>.
=head3 The C<$input> parameter
The complete array will be walked to ensure that it only
contains valid filenames before any data is uncompressed.
-
-
=item An Input FileGlob string
If C<$input> is a string that is delimited by the characters "<" and ">"
See L<File::GlobMapper|File::GlobMapper> for more details.
-
=back
If the C<$input> parameter is any other type, C<undef> will be returned.
-
-
=head3 The C<$output> parameter
The parameter C<$output> is used to control the destination of the
will be written to it.
The string '-' can be used as an alias for standard output.
-
=item A scalar reference
If C<$output> is a scalar reference, the uncompressed data will be
stored in C<$$output>.
-
-
=item An Array Reference
If C<$output> is an array reference, the uncompressed data will be
If the C<$output> parameter is any other type, C<undef> will be returned.
-
-
=head2 Notes
-
When C<$input> maps to multiple compressed files/buffers and C<$output> is
a single file/buffer, after uncompression C<$output> will contain a
concatenation of all the uncompressed data from each of the input
files/buffers.
-
-
-
-
=head2 Optional Parameters
Unless specified below, the optional parameters for C<anyuncompress>,
This parameter defaults to 0.
-
=item C<< BinModeOut => 0|1 >>
When writing to a file or filehandle, set C<binmode> before writing to the
Defaults to 0.
-
-
-
-
=item C<< Append => 0|1 >>
TODO
=item C<< MultiStream => 0|1 >>
-
If the input file/buffer contains multiple compressed data streams, this
option will uncompress the whole lot as a single data stream.
Defaults to 0.
-
-
-
-
=item C<< TrailingData => $scalar >>
Returns the data, if any, that is present immediately after the compressed
Don't bother using C<trailingData> if the input is a filename.
-
-
If you know the length of the compressed data stream before you start
uncompressing, you can avoid having to use C<trailingData> by setting the
C<InputLength> option.
-
-
=back
-
-
-
=head2 Examples
To read the contents of the file C<file1.txt.Compressed> and write the
anyuncompress $input => $output
or die "anyuncompress failed: $AnyUncompressError\n";
-
To read from an existing Perl filehandle, C<$input>, and write the
uncompressed data to a buffer, C<$buffer>.
The format of the constructor for IO::Uncompress::AnyUncompress is shown below
-
my $z = new IO::Uncompress::AnyUncompress $input [OPTS]
or die "IO::Uncompress::AnyUncompress failed: $AnyUncompressError\n";
read from it.
The string '-' can be used as an alias for standard input.
-
=item A scalar reference
If C<$input> is a scalar reference, the compressed data will be read from
=head2 Constructor Options
-
The option names defined below are case insensitive and can be optionally
prefixed by a '-'. So all of the following are valid
=item C<< MultiStream => 0|1 >>
-
-
Allows multiple concatenated compressed streams to be treated as a single
compressed stream. Decompression will stop once either the end of the
file/buffer is reached, an error is encountered (premature eof, corrupt
This parameter defaults to 0.
-
=item C<< Prime => $string >>
This option will uncompress the contents of C<$string> before processing the
the file pointer will be left pointing to the first byte directly after the
compressed data stream.
-
-
This option defaults to off.
=item C<< Append => 0|1 >>
=item C<< Strict => 0|1 >>
-
-
This option controls whether the extra checks defined below are used when
carrying out the decompression. When Strict is on, the extra tests are
carried out, when Strict is off they are not.
The default for this option is off.
-
-
-
-
-
-
-
-
-
-
=item C<< RawInflate => 0|1 >>
When auto-detecting the compressed format, try to test for raw-deflate (RFC
Defaults to 0.
-
-
-
-
-
=back
=head2 Examples
Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
or a negative number on error.
-
=head2 getline
Usage is
determine what constitutes an end of line. Paragraph mode, record mode and
file slurp mode are all supported.
-
=head2 getc
Usage is
$char = $z->ungetc($string)
-
-
-
=head2 getHeaderInfo
Usage is
or hash references (in array context) that contains information about each
of the header fields in the compressed data stream(s).
-
-
-
=head2 tell
Usage is
$z->eof();
eof($z);
-
-
Returns true if the end of the compressed input stream has been reached.
-
-
=head2 seek
$z->seek($position, $whence);
seek($z, $position, $whence);
-
-
-
Provides a sub-set of the C<seek> functionality, with the restriction
that it is only legal to seek forward in the input file/buffer.
It is a fatal error to attempt to seek backward.
-
-
The C<$whence> parameter takes one the usual values, namely SEEK_SET,
SEEK_CUR or SEEK_END.
$z->input_line_number()
$z->input_line_number(EXPR)
-
-
Returns the current uncompressed line number. If C<EXPR> is present it has
the effect of setting the line number. Note that setting the line number
does not change the current position within the file/buffer being read.
The contents of C<$/> are used to to determine what constitutes a line
terminator.
-
-
=head2 fileno
$z->fileno()
fileno($z)
-If the C<$z> object is associated with a file or a filehandle, this method
-will return the underlying file descriptor.
+If the C<$z> object is associated with a file or a filehandle, C<fileno>
+will return the underlying file descriptor. Once the C<close> method is
+called C<fileno> will return C<undef>.
-If the C<$z> object is is associated with a buffer, this method will
-return undef.
+If the C<$z> object is is associated with a buffer, this method will return
+C<undef>.
=head2 close
$z->close() ;
close $z ;
-
-
Closes the output file/buffer.
-
-
For most versions of Perl this method will be automatically invoked if
the IO::Uncompress::AnyUncompress object is destroyed (either explicitly or by the
variable with the reference to the object going out of scope). The
object was created, and the object is associated with a file, the
underlying file will also be closed.
-
-
-
=head2 nextStream
Usage is
Don't bother using C<trailingData> if the input is a filename.
-
-
If you know the length of the compressed data stream before you start
uncompressing, you can avoid having to use C<trailingData> by setting the
C<InputLength> option in the constructor.
=head1 EXAMPLES
-
-
-
=head1 SEE ALSO
L<Compress::Zlib>, L<IO::Compress::Gzip>, L<IO::Uncompress::Gunzip>, L<IO::Compress::Deflate>, L<IO::Uncompress::Inflate>, L<IO::Compress::RawDeflate>, L<IO::Uncompress::RawInflate>, L<IO::Compress::Bzip2>, L<IO::Uncompress::Bunzip2>, L<IO::Compress::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Uncompress::AnyInflate>
L<Archive::Tar|Archive::Tar>,
L<IO::Zlib|IO::Zlib>
-
-
-
-
=head1 AUTHOR
This module was written by Paul Marquess, F<pmqs@cpan.org>.
-
-
=head1 MODIFICATION HISTORY
See the Changes file.
=head1 COPYRIGHT AND LICENSE
-Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
+Copyright (c) 2005-2008 Paul Marquess. All rights reserved.
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
@ISA = qw(Exporter IO::File);
-$VERSION = '2.008';
+$VERSION = '2.009';
use constant G_EOF => 0 ;
use constant G_ERR => -1 ;
-use IO::Compress::Base::Common 2.008 ;
+use IO::Compress::Base::Common 2.009 ;
#use Parse::Parameters ;
use IO::File ;
#Exporter::export_ok_tags('all') ;
+
sub smartRead
{
my $self = $_[0];
my $get_size = $size - $offset ;
- #if ( defined *$self->{InputLength} ) {
- # $get_size = min($get_size, *$self->{InputLengthRemaining});
- #}
-
- if (defined *$self->{FH})
- { *$self->{FH}->read($$out, $get_size, $offset) }
+ if (defined *$self->{FH}) {
+ if ($offset) {
+ # Not using this
+ #
+ # *$self->{FH}->read($$out, $get_size, $offset);
+ #
+ # because the filehandle may not support the offset parameter
+ # An example is Net::FTP
+ my $tmp = '';
+ *$self->{FH}->read($tmp, $get_size) > 0 &&
+ (substr($$out, $offset) = $tmp);
+ }
+ else
+ { *$self->{FH}->read($$out, $get_size) }
+ }
elsif (defined *$self->{InputEvent}) {
my $got = 1 ;
while (length $$out < $size) {
return 0 if length *$self->{Prime} || *$self->{PushMode};
if (defined *$self->{FH})
- { *$self->{FH}->eof() }
+ {
+ # Could use
+ #
+ # *$self->{FH}->eof()
+ #
+ # here, but this can cause trouble if
+ # the filehandle is itself a tied handle, but it uses sysread.
+ # Then we get into mixing buffered & non-buffered IO, which will cause trouble
+
+ my $info = $self->getErrInfo();
+
+ my $buffer = '';
+ my $status = $self->smartRead(\$buffer, 1);
+ $self->pushBack($buffer) if length $buffer;
+ $self->setErrInfo($info);
+
+ return $status == 0 ;
+ }
elsif (defined *$self->{InputEvent})
{ *$self->{EventEof} }
else
${ *$self->{Error} } = '' ;
}
+sub getErrInfo
+{
+ my $self = shift ;
+
+ return [ *$self->{ErrorNo}, ${ *$self->{Error} } ] ;
+}
+
+sub setErrInfo
+{
+ my $self = shift ;
+ my $ref = shift;
+
+ *$self->{ErrorNo} = $ref->[0] ;
+ ${ *$self->{Error} } = $ref->[1] ;
+}
+
sub saveStatus
{
my $self = shift ;
my $magic = $self->ckMagic();
#*$self->{EndStream} = 0 ;
- if ( ! $magic) {
+ if ( ! defined $magic) {
if (! *$self->{Transparent} )
{
*$self->{EndStream} = 1 ;
=head1 NAME
-
IO::Uncompress::Base - Base Class for IO::Uncompress modules
-
=head1 SYNOPSIS
use IO::Uncompress::Base ;
=head1 DESCRIPTION
-
This module is not intended for direct use in application code. Its sole
purpose if to to be sub-classed by IO::Unompress modules.
-
-
-
=head1 SEE ALSO
L<Compress::Zlib>, L<IO::Compress::Gzip>, L<IO::Uncompress::Gunzip>, L<IO::Compress::Deflate>, L<IO::Uncompress::Inflate>, L<IO::Compress::RawDeflate>, L<IO::Uncompress::RawInflate>, L<IO::Compress::Bzip2>, L<IO::Uncompress::Bunzip2>, L<IO::Compress::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
L<Archive::Tar|Archive::Tar>,
L<IO::Zlib|IO::Zlib>
-
-
-
-
=head1 AUTHOR
This module was written by Paul Marquess, F<pmqs@cpan.org>.
-
-
=head1 MODIFICATION HISTORY
See the Changes file.
=head1 COPYRIGHT AND LICENSE
-Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
+Copyright (c) 2005-2008 Paul Marquess. All rights reserved.
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
-
--- /dev/null
+
+=head1 NAME
+
+IO::Compress::Base::FAQ -- Frequently Asked Questions about IO::Compress::Base
+
+=head1 DESCRIPTION
+
+Common questions answered.
+
+=head2 Compatibility with Unix compress/uncompress.
+
+This module is not compatible with Unix C<compress>.
+
+If you have the C<uncompress> program available, you can use this to read
+compressed files
+
+ open F, "uncompress -c $filename |";
+ while (<F>)
+ {
+ ...
+
+Alternatively, if you have the C<gunzip> program available, you can use
+this to read compressed files
+
+ open F, "gunzip -c $filename |";
+ while (<F>)
+ {
+ ...
+
+and this to write compress files, if you have the C<compress> program
+available
+
+ open F, "| compress -c $filename ";
+ print F "data";
+ ...
+ close F ;
+
+=head2 Accessing .tar.Z files
+
+See previous FAQ item.
+
+If the C<Archive::Tar> module is installed and either the C<uncompress> or
+C<gunzip> programs are available, you can use one of these workarounds to
+read C<.tar.Z> files.
+
+Firstly with C<uncompress>
+
+ use strict;
+ use warnings;
+ use Archive::Tar;
+
+ open F, "uncompress -c $filename |";
+ my $tar = Archive::Tar->new(*F);
+ ...
+
+and this with C<gunzip>
+
+ use strict;
+ use warnings;
+ use Archive::Tar;
+
+ open F, "gunzip -c $filename |";
+ my $tar = Archive::Tar->new(*F);
+ ...
+
+Similarly, if the C<compress> program is available, you can use this to
+write a C<.tar.Z> file
+
+ use strict;
+ use warnings;
+ use Archive::Tar;
+ use IO::File;
+
+ my $fh = new IO::File "| compress -c >$filename";
+ my $tar = Archive::Tar->new();
+ ...
+ $tar->write($fh);
+ $fh->close ;
+
+=head2 Accessing Zip Files
+
+This module does not support reading/writing zip files.
+
+Support for reading/writing zip files is included with the
+C<IO::Compress::Zip> and C<IO::Uncompress::Unzip> modules.
+
+The primary focus of the C<IO::Compress::Zip> and C<IO::Uncompress::Unzip>
+modules is to provide an C<IO::File> compatible streaming read/write
+interface to zip files/buffers. They are not fully flegged archivers. If
+you are looking for an archiver check out the C<Archive::Zip> module. You
+can find it on CPAN at
+
+ http://www.cpan.org/modules/by-module/Archive/Archive-Zip-*.tar.gz
+
+=head2 Compressed files and Net::FTP
+
+The C<Net::FTP> module provides two low-level methods called C<stor> and
+C<retr> that both return filehandles. These filehandles can used with the
+C<IO::Compress/Uncompress> modules to compress or uncompress files read
+from or written to an FTP Server on the fly, without having to create a
+temporary file.
+
+Firstly, here is code that uses C<retr> to uncompressed a file as it is
+read from the FTP Server.
+
+ use Net::FTP;
+ use IO::Uncompress::Bunzip2 qw(:all);
+
+ my $ftp = new Net::FTP ...
+
+ my $retr_fh = $ftp->retr($compressed_filename);
+ bunzip2 $retr_fh => $outFilename, AutoClose => 1
+ or die "Cannot uncompress '$compressed_file': $Bunzip2Error\n";
+
+and this to compress a file as it is written to the FTP Server
+
+ use Net::FTP;
+ use IO::Compress::Bzip2 qw(:all);
+
+ my $stor_fh = $ftp->stor($filename);
+ bzip2 "filename" => $stor_fh, AutoClose => 1
+ or die "Cannot compress '$filename': $Bzip2Error\n";
+
+=head2 How do I recompress using a different compression?
+
+This is easier that you might expect if you realise that all the
+C<IO::Compress::*> objects are derived from C<IO::File> and that all the
+C<IO::Uncompress::*> modules can read from an C<IO::File> filehandle.
+
+So, for example, say you have a file compressed with gzip that you want to
+recompress with bzip2. Here is all that is needed to carry out the
+recompression.
+
+ use IO::Uncompress::Gunzip ':all';
+ use IO::Compress::Bzip2 ':all';
+
+ my $gzipFile = "somefile.gz";
+ my $bzipFile = "somefile.bz2";
+
+ my $gunzip = new IO::Uncompress::Gunzip $gzipFile
+ or die "Cannot gunzip $gzipFile: $GunzipError\n" ;
+
+ bzip2 $gunzip => $bzipFile
+ or die "Cannot bzip2 to $bzipFile: $Bzip2Error\n" ;
+
+Note, there is a limitation of this technique. Some compression file
+formats store extra information along with the compressed data payload. For
+example, gzip can optionally store the original filename and Zip stores a
+lot of information about the original file. If the original compressed file
+contains any of this extra information, it will not be transferred to the
+new compressed file usign the technique above.
+
+=head2 Using C<InputLength> to uncompress data embedded in a larger file/buffer.
+
+A fairly common use-case is where compressed data is embedded in a larger
+file/buffer and you want to read both.
+
+As an example consider the structure of a zip file. This is a well-defined
+file format that mixes both compressed and uncompressed sections of data in
+a single file.
+
+For the purposes of this discussion you can think of a zip file as sequence
+of compressed data streams, each of which is prefixed by an uncompressed
+local header. The local header contains information about the compressed
+data stream, including the name of the compressed file and, in particular,
+the length of the compressed data stream.
+
+To illustrate how to use C<InputLength> here is a script that walks a zip
+file and prints out how many lines are in each compressed file (if you
+intend write code to walking through a zip file for real see
+L<IO::Uncompress::Unzip/"Walking through a zip file"> )
+
+ use strict;
+ use warnings;
+
+ use IO::File;
+ use IO::Uncompress::RawInflate qw(:all);
+
+ use constant ZIP_LOCAL_HDR_SIG => 0x04034b50;
+ use constant ZIP_LOCAL_HDR_LENGTH => 30;
+
+ my $file = $ARGV[0] ;
+
+ my $fh = new IO::File "<$file"
+ or die "Cannot open '$file': $!\n";
+
+ while (1)
+ {
+ my $sig;
+ my $buffer;
+
+ my $x ;
+ ($x = $fh->read($buffer, ZIP_LOCAL_HDR_LENGTH)) == ZIP_LOCAL_HDR_LENGTH
+ or die "Truncated file: $!\n";
+
+ my $signature = unpack ("V", substr($buffer, 0, 4));
+
+ last unless $signature == ZIP_LOCAL_HDR_SIG;
+
+ # Read Local Header
+ my $gpFlag = unpack ("v", substr($buffer, 6, 2));
+ my $compressedMethod = unpack ("v", substr($buffer, 8, 2));
+ my $compressedLength = unpack ("V", substr($buffer, 18, 4));
+ my $uncompressedLength = unpack ("V", substr($buffer, 22, 4));
+ my $filename_length = unpack ("v", substr($buffer, 26, 2));
+ my $extra_length = unpack ("v", substr($buffer, 28, 2));
+
+ my $filename ;
+ $fh->read($filename, $filename_length) == $filename_length
+ or die "Truncated file\n";
+
+ $fh->read($buffer, $extra_length) == $extra_length
+ or die "Truncated file\n";
+
+ if ($compressedMethod != 8 && $compressedMethod != 0)
+ {
+ warn "Skipping file '$filename' - not deflated $compressedMethod\n";
+ $fh->read($buffer, $compressedLength) == $compressedLength
+ or die "Truncated file\n";
+ next;
+ }
+
+ if ($compressedMethod == 0 && $gpFlag & 8 == 8)
+ {
+ die "Streamed Stored not supported for '$filename'\n";
+ }
+
+ next if $compressedLength == 0;
+
+ # Done reading the Local Header
+
+ my $inf = new IO::Uncompress::RawInflate $fh,
+ Transparent => 1,
+ InputLength => $compressedLength
+ or die "Cannot uncompress $file [$filename]: $RawInflateError\n" ;
+
+ my $line_count = 0;
+
+ while (<$inf>)
+ {
+ ++ $line_count;
+ }
+
+ print "$filename: $line_count\n";
+ }
+
+The majority of the code above is concerned with reading the zip local
+header data. The code that I want to focus on is at the bottom.
+
+ while (1) {
+
+ # read local zip header data
+ # get $filename
+ # get $compressedLength
+
+ my $inf = new IO::Uncompress::RawInflate $fh,
+ Transparent => 1,
+ InputLength => $compressedLength
+ or die "Cannot uncompress $file [$filename]: $RawInflateError\n" ;
+
+ my $line_count = 0;
+
+ while (<$inf>)
+ {
+ ++ $line_count;
+ }
+
+ print "$filename: $line_count\n";
+ }
+
+The call to C<IO::Uncompress::RawInflate> creates a new filehandle C<$inf>
+that can be used to read from the parent filehandle C<$fh>, uncompressing
+it as it goes. The use of the C<InputLength> option will guarantee that
+I<at most> C<$compressedLength> bytes of compressed data will be read from
+the C<$fh> filehandle (The only exception is for an error case like a
+truncated file or a corrupt data stream).
+
+This means that once RawInflate is finished C<$fh> will be left at the
+byte directly after the compressed data stream.
+
+Now consider what the code looks like without C<InputLength>
+
+ while (1) {
+
+ # read local zip header data
+ # get $filename
+ # get $compressedLength
+
+ # read all the compressed data into $data
+ read($fh, $data, $compressedLength);
+
+ my $inf = new IO::Uncompress::RawInflate \$data,
+ Transparent => 1,
+ or die "Cannot uncompress $file [$filename]: $RawInflateError\n" ;
+
+ my $line_count = 0;
+
+ while (<$inf>)
+ {
+ ++ $line_count;
+ }
+
+ print "$filename: $line_count\n";
+ }
+
+The difference here is the addition of the temporary variable C<$data>.
+This is used to store a copy of the compressed data while it is being
+uncompressed.
+
+If you know that C<$compressedLength> isn't that big then using temporary
+storage won't be a problem. But if C<$compressedLength> is very large or
+you are writing an application that other people will use, and so have no
+idea how big C<$compressedLength> will be, it could be an issue.
+
+Using C<InputLength> avoids the use of temporary storage and means the
+application can cope with large compressed data streams.
+
+One final point -- obviously C<InputLength> can only be used whenever you
+know the length of the compressed data beforehand, like here with a zip
+file.
+
+=head1 SEE ALSO
+
+L<Compress::Zlib>, L<IO::Compress::Gzip>, L<IO::Uncompress::Gunzip>, L<IO::Compress::Deflate>, L<IO::Uncompress::Inflate>, L<IO::Compress::RawDeflate>, L<IO::Uncompress::RawInflate>, L<IO::Compress::Bzip2>, L<IO::Uncompress::Bunzip2>, L<IO::Compress::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
+
+L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
+
+L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
+L<Archive::Tar|Archive::Tar>,
+L<IO::Zlib|IO::Zlib>
+
+=head1 AUTHOR
+
+This module was written by Paul Marquess, F<pmqs@cpan.org>.
+
+=head1 MODIFICATION HISTORY
+
+See the Changes file.
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright (c) 2005-2008 Paul Marquess. All rights reserved.
+
+This program is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+
$extra = 1
if eval { require Test::NoWarnings ; import Test::NoWarnings; 1 };
- plan tests => 78 + $extra ;
+ plan tests => 80 + $extra ;
use_ok('Scalar::Util');
use_ok('IO::Compress::Base::Common');
$$xx_ref = 666 ;
is $xx, 666;
+ my $got1 = ParseParameters(1, {'Fred' => [1, 1, Parse_writable_scalar, undef]}, $got) ;
+ ok $got->parsed('Fred'), "parsed" ;
+ $xx_ref = $got->value('Fred');
+ $$xx_ref = 666 ;
+ is $xx, 666;
}
My::testParseParameters();
CHANGES
-------
+ 2.009 20 April 2008
+
+ * IO::Compress::Zip
+
+ - Added exUnix2 option to allow storing of UID & GID.
+ - When running on a Unix derivative the ExtAttr option now defaults
+ to the equivalent of 0666. For all other systems the default
+ remains 0.
+
2.008 2 November 2007
* Minor documentation changes in README
use strict ;
require 5.004 ;
-$::VERSION = '2.008' ;
+$::VERSION = '2.009' ;
use private::MakeUtil;
use ExtUtils::MakeMaker 5.16 ;
IO-Compress-Zlib
- Version 2.008
+ Version 2.009
- 2nd November 2007
+ 20th April 2008
-
- Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
+ Copyright (c) 2005-2008 Paul Marquess. All rights reserved.
This program is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.
-
-
-
DESCRIPTION
-----------
-
This module provides a Perl interface to allow reading and writing of RFC
1950, 1951, 1952 (i.e. gzip) and zip files/buffers.
-
-
-
-
PREREQUISITES
-------------
Before you can build IO-Compress-Zlib you need to have the following
installed on your system:
-
* Perl 5.004 or better.
* Compress::Raw::Zlib
* IO::Compress::Base
-
-
-
-
BUILDING THE MODULE
-------------------
make
make test
-
-
INSTALLATION
------------
make install
-
-
-
-
TROUBLESHOOTING
---------------
-
-
-
-
-
-
-
-
The t/020isize Test Suite
------------------------
This test suite checks that IO-Compress-Zlib can cope with gzip files
that are larger than 2^32 bytes.
-By default these test are NOT run when you do a "make test". If you
+By default these tests are NOT run when you do a "make test". If you
really want to run them, you need to execute "make longtest".
Be warned though -- this test suite can take hours to run on a slow box.
run out of memory during this test. This should not be considered a bug
in the IO-Compress-Zlib module.
-
-
-
FEEDBACK
--------
If you haven't installed IO-Compress-Zlib then search IO::Compress::Gzip.pm
for a line like this:
- $VERSION = "2.008" ;
-
-
+ $VERSION = "2.009" ;
2. If you are having problems building IO-Compress-Zlib, send me a
complete log of what happened. Start by unpacking the IO-Compress-Zlib
make
make test TEST_VERBOSE=1
-
Paul Marquess <pmqs@cpan.org>
use warnings;
use bytes;
-use IO::Compress::Base::Common 2.008 qw(:Status);
+use IO::Compress::Base::Common 2.009 qw(:Status);
-use Compress::Raw::Zlib 2.008 qw(Z_OK Z_FINISH MAX_WBITS) ;
+use Compress::Raw::Zlib 2.009 qw(Z_OK Z_FINISH MAX_WBITS) ;
our ($VERSION);
-$VERSION = '2.008';
+$VERSION = '2.009';
sub mkCompObject
{
use warnings;
use bytes;
-use IO::Compress::Base::Common 2.008 qw(:Status);
+use IO::Compress::Base::Common 2.009 qw(:Status);
our ($VERSION);
-$VERSION = '2.008';
+$VERSION = '2.009';
sub mkCompObject
{
require Exporter ;
-use IO::Compress::RawDeflate 2.008 ;
+use IO::Compress::RawDeflate 2.009 ;
-use Compress::Raw::Zlib 2.008 ;
-use IO::Compress::Zlib::Constants 2.008 ;
-use IO::Compress::Base::Common 2.008 qw(createSelfTiedObject);
+use Compress::Raw::Zlib 2.009 ;
+use IO::Compress::Zlib::Constants 2.009 ;
+use IO::Compress::Base::Common 2.009 qw(createSelfTiedObject);
our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $DeflateError);
-$VERSION = '2.008';
+$VERSION = '2.009';
$DeflateError = '';
@ISA = qw(Exporter IO::Compress::RawDeflate);
=head1 NAME
-
-
IO::Compress::Deflate - Write RFC 1950 files/buffers
use IO::Compress::Deflate qw(deflate $DeflateError) ;
-
my $status = deflate $input => $output [,OPTS]
or die "deflate failed: $DeflateError\n";
=head1 DESCRIPTION
-
This module provides a Perl interface that allows writing compressed
data to files or buffer as defined in RFC 1950.
-
-
-
-
-
-
-
-
-
-
For reading RFC 1950 files/buffers, see the companion module
L<IO::Uncompress::Inflate|IO::Uncompress::Inflate>.
-
=head1 Functional Interface
A top-level function, C<deflate>, is provided to carry out
deflate $input => $output [,OPTS]
or die "deflate failed: $DeflateError\n";
-
-
The functional interface needs Perl5.005 or better.
-
=head2 deflate $input => $output [, OPTS]
-
C<deflate> expects at least two parameters, C<$input> and C<$output>.
=head3 The C<$input> parameter
The complete array will be walked to ensure that it only
contains valid filenames before any data is compressed.
-
-
=item An Input FileGlob string
If C<$input> is a string that is delimited by the characters "<" and ">"
See L<File::GlobMapper|File::GlobMapper> for more details.
-
=back
If the C<$input> parameter is any other type, C<undef> will be returned.
-
-
=head3 The C<$output> parameter
The parameter C<$output> is used to control the destination of the
will be written to it.
The string '-' can be used as an alias for standard output.
-
=item A scalar reference
If C<$output> is a scalar reference, the compressed data will be
stored in C<$$output>.
-
-
=item An Array Reference
If C<$output> is an array reference, the compressed data will be
If the C<$output> parameter is any other type, C<undef> will be returned.
-
-
=head2 Notes
-
-
When C<$input> maps to multiple files/buffers and C<$output> is a single
file/buffer the input files/buffers will be stored
in C<$output> as a concatenated series of compressed data streams.
-
-
-
-
-
=head2 Optional Parameters
Unless specified below, the optional parameters for C<deflate>,
This parameter defaults to 0.
-
=item C<< BinModeIn => 0|1 >>
When reading from a file or filehandle, set C<binmode> before reading.
Defaults to 0.
-
-
-
-
=item C<< Append => 0|1 >>
TODO
-
-
=back
-
-
=head2 Examples
To read the contents of the file C<file1.txt> and write the compressed
deflate $input => "$input.1950"
or die "deflate failed: $DeflateError\n";
-
To read from an existing Perl filehandle, C<$input>, and write the
compressed data to a buffer, C<$buffer>.
or die "Error compressing '$input': $DeflateError\n";
}
-
=head1 OO Interface
=head2 Constructor
written to it.
The string '-' can be used as an alias for standard output.
-
=item A scalar reference
If C<$output> is a scalar reference, the compressed data will be stored
This parameter defaults to 0.
-
-
-
-
=item C<< Merge => 0|1 >>
This option is used to compress input data and append it to an existing
compressed data stream in C<$output>. The end result is a single compressed
data stream stored in C<$output>.
-
-
It is a fatal error to attempt to use this option when C<$output> is not an
RFC 1950 data stream.
-
-
There are a number of other limitations with the C<Merge> option:
=over 5
=back
-
This parameter defaults to 0.
-
-
=item -Level
Defines the compression level used by zlib. The value should either be
The default is Z_DEFAULT_STRATEGY.
-
-
-
-
-
=item C<< Strict => 0|1 >>
-
-
This is a placeholder option.
-
-
=back
=head2 Examples
Usage is
-
$z->flush;
$z->flush($flush_type);
-
Flushes any pending compressed data to the output file/buffer.
-
This method takes an optional parameter, C<$flush_type>, that controls
how the flushing will be carried out. By default the C<$flush_type>
used is C<Z_FINISH>. Other valid values for C<$flush_type> are
can seriously degrade the level of compression achieved. See the C<zlib>
documentation for details.
-
Returns true on success.
-
=head2 tell
Usage is
$z->eof();
eof($z);
-
-
Returns true if the C<close> method has been called.
-
-
=head2 seek
$z->seek($position, $whence);
seek($z, $position, $whence);
-
-
-
Provides a sub-set of the C<seek> functionality, with the restriction
that it is only legal to seek forward in the output file/buffer.
It is a fatal error to attempt to seek backward.
Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
-
-
The C<$whence> parameter takes one the usual values, namely SEEK_SET,
SEEK_CUR or SEEK_END.
$z->input_line_number()
$z->input_line_number(EXPR)
-
This method always returns C<undef> when compressing.
-
-
=head2 fileno
$z->fileno()
fileno($z)
-If the C<$z> object is associated with a file or a filehandle, this method
-will return the underlying file descriptor.
+If the C<$z> object is associated with a file or a filehandle, C<fileno>
+will return the underlying file descriptor. Once the C<close> method is
+called C<fileno> will return C<undef>.
-If the C<$z> object is is associated with a buffer, this method will
-return undef.
+If the C<$z> object is is associated with a buffer, this method will return
+C<undef>.
=head2 close
$z->close() ;
close $z ;
-
-
Flushes any pending compressed data and then closes the output file/buffer.
-
-
For most versions of Perl this method will be automatically invoked if
the IO::Compress::Deflate object is destroyed (either explicitly or by the
variable with the reference to the object going out of scope). The
object was created, and the object is associated with a file, the
underlying file will also be closed.
-
-
-
=head2 newStream([OPTS])
Usage is
See the L</"Constructor Options"> section for more details.
-
=head2 deflateParams
Usage is
TODO
-
=head1 Importing
-
A number of symbolic constants are required by some methods in
C<IO::Compress::Deflate>. None are imported by default.
-
-
=over 5
=item :all
-
Imports C<deflate>, C<$DeflateError> and all symbolic
constants that can be used by C<IO::Compress::Deflate>. Same as doing this
Import all symbolic constants. Same as doing this
-
use IO::Compress::Deflate qw(:flush :level :strategy) ;
-
=item :flush
These symbolic constants are used by the C<flush> method.
Z_BEST_COMPRESSION
Z_DEFAULT_COMPRESSION
-
=item :strategy
These symbolic constants are used by the C<Strategy> option in the constructor.
=back
-For
-
=head1 EXAMPLES
-TODO
-
-
-
-
-
-
+=head2 Apache::GZip Revisited
+See L<IO::Compress::Zlib::FAQ|IO::Compress::Zlib::FAQ/"Apache::GZip Revisited">
+
+=head2 Working with Net::FTP
+See L<IO::Compress::Zlib::FAQ|IO::Compress::Zlib::FAQ/"Compressed files and Net::FTP">
=head1 SEE ALSO
L<Archive::Tar|Archive::Tar>,
L<IO::Zlib|IO::Zlib>
-
For RFC 1950, 1951 and 1952 see
F<http://www.faqs.org/rfcs/rfc1950.html>,
F<http://www.faqs.org/rfcs/rfc1951.html> and
The primary site for gzip is F<http://www.gzip.org>.
-
-
-
=head1 AUTHOR
This module was written by Paul Marquess, F<pmqs@cpan.org>.
-
-
=head1 MODIFICATION HISTORY
See the Changes file.
=head1 COPYRIGHT AND LICENSE
-Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
+Copyright (c) 2005-2008 Paul Marquess. All rights reserved.
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
-
use bytes;
-use IO::Compress::RawDeflate 2.008 ;
+use IO::Compress::RawDeflate 2.009 ;
-use Compress::Raw::Zlib 2.008 ;
-use IO::Compress::Base::Common 2.008 qw(:Status :Parse createSelfTiedObject);
-use IO::Compress::Gzip::Constants 2.008 ;
-use IO::Compress::Zlib::Extra 2.008 ;
+use Compress::Raw::Zlib 2.009 ;
+use IO::Compress::Base::Common 2.009 qw(:Status :Parse createSelfTiedObject);
+use IO::Compress::Gzip::Constants 2.009 ;
+use IO::Compress::Zlib::Extra 2.009 ;
BEGIN
{
our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $GzipError);
-$VERSION = '2.008';
+$VERSION = '2.009';
$GzipError = '' ;
@ISA = qw(Exporter IO::Compress::RawDeflate);
=head1 NAME
-
-
IO::Compress::Gzip - Write RFC 1952 files/buffers
use IO::Compress::Gzip qw(gzip $GzipError) ;
-
my $status = gzip $input => $output [,OPTS]
or die "gzip failed: $GzipError\n";
=head1 DESCRIPTION
-
This module provides a Perl interface that allows writing compressed
data to files or buffer as defined in RFC 1952.
-
-
-
-
All the gzip headers defined in RFC 1952 can be created using
this module.
-
-
-
-
-
-
For reading RFC 1952 files/buffers, see the companion module
L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip>.
-
=head1 Functional Interface
A top-level function, C<gzip>, is provided to carry out
gzip $input => $output [,OPTS]
or die "gzip failed: $GzipError\n";
-
-
The functional interface needs Perl5.005 or better.
-
=head2 gzip $input => $output [, OPTS]
-
C<gzip> expects at least two parameters, C<$input> and C<$output>.
=head3 The C<$input> parameter
The complete array will be walked to ensure that it only
contains valid filenames before any data is compressed.
-
-
=item An Input FileGlob string
If C<$input> is a string that is delimited by the characters "<" and ">"
See L<File::GlobMapper|File::GlobMapper> for more details.
-
=back
If the C<$input> parameter is any other type, C<undef> will be returned.
-
In addition, if C<$input> is a simple filename, the default values for
the C<Name> and C<Time> options will be sourced from that file.
explicitly setting the C<Name> and C<Time> options or by setting the
C<Minimal> parameter.
-
-
=head3 The C<$output> parameter
The parameter C<$output> is used to control the destination of the
will be written to it.
The string '-' can be used as an alias for standard output.
-
=item A scalar reference
If C<$output> is a scalar reference, the compressed data will be
stored in C<$$output>.
-
-
=item An Array Reference
If C<$output> is an array reference, the compressed data will be
If the C<$output> parameter is any other type, C<undef> will be returned.
-
-
=head2 Notes
-
-
When C<$input> maps to multiple files/buffers and C<$output> is a single
file/buffer the input files/buffers will be stored
in C<$output> as a concatenated series of compressed data streams.
-
-
-
-
-
=head2 Optional Parameters
Unless specified below, the optional parameters for C<gzip>,
This parameter defaults to 0.
-
=item C<< BinModeIn => 0|1 >>
When reading from a file or filehandle, set C<binmode> before reading.
Defaults to 0.
-
-
-
-
=item C<< Append => 0|1 >>
TODO
-
-
=back
-
-
=head2 Examples
To read the contents of the file C<file1.txt> and write the compressed
gzip $input => "$input.gz"
or die "gzip failed: $GzipError\n";
-
To read from an existing Perl filehandle, C<$input>, and write the
compressed data to a buffer, C<$buffer>.
or die "Error compressing '$input': $GzipError\n";
}
-
=head1 OO Interface
=head2 Constructor
written to it.
The string '-' can be used as an alias for standard output.
-
=item A scalar reference
If C<$output> is a scalar reference, the compressed data will be stored
This parameter defaults to 0.
-
-
-
-
=item C<< Merge => 0|1 >>
This option is used to compress input data and append it to an existing
compressed data stream in C<$output>. The end result is a single compressed
data stream stored in C<$output>.
-
-
It is a fatal error to attempt to use this option when C<$output> is not an
RFC 1952 data stream.
-
-
There are a number of other limitations with the C<Merge> option:
=over 5
=back
-
This parameter defaults to 0.
-
-
=item -Level
Defines the compression level used by zlib. The value should either be
The default is Z_DEFAULT_STRATEGY.
-
-
-
-
-
=item C<< Minimal => 0|1 >>
If specified, this option will force the creation of the smallest possible
If C<< Level => Z_BEST_COMPRESSION >> has been specified then XFL is set to 4.
Otherwise XFL is set to 0.
-
-
=item C<< Strict => 0|1 >>
-
-
C<Strict> will optionally police the values supplied with other options
to ensure they are compliant with RFC1952.
=back
-
-
=back
=head2 Examples
Usage is
-
$z->flush;
$z->flush($flush_type);
-
Flushes any pending compressed data to the output file/buffer.
-
This method takes an optional parameter, C<$flush_type>, that controls
how the flushing will be carried out. By default the C<$flush_type>
used is C<Z_FINISH>. Other valid values for C<$flush_type> are
can seriously degrade the level of compression achieved. See the C<zlib>
documentation for details.
-
Returns true on success.
-
=head2 tell
Usage is
$z->eof();
eof($z);
-
-
Returns true if the C<close> method has been called.
-
-
=head2 seek
$z->seek($position, $whence);
seek($z, $position, $whence);
-
-
-
Provides a sub-set of the C<seek> functionality, with the restriction
that it is only legal to seek forward in the output file/buffer.
It is a fatal error to attempt to seek backward.
Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
-
-
The C<$whence> parameter takes one the usual values, namely SEEK_SET,
SEEK_CUR or SEEK_END.
$z->input_line_number()
$z->input_line_number(EXPR)
-
This method always returns C<undef> when compressing.
-
-
=head2 fileno
$z->fileno()
fileno($z)
-If the C<$z> object is associated with a file or a filehandle, this method
-will return the underlying file descriptor.
+If the C<$z> object is associated with a file or a filehandle, C<fileno>
+will return the underlying file descriptor. Once the C<close> method is
+called C<fileno> will return C<undef>.
-If the C<$z> object is is associated with a buffer, this method will
-return undef.
+If the C<$z> object is is associated with a buffer, this method will return
+C<undef>.
=head2 close
$z->close() ;
close $z ;
-
-
Flushes any pending compressed data and then closes the output file/buffer.
-
-
For most versions of Perl this method will be automatically invoked if
the IO::Compress::Gzip object is destroyed (either explicitly or by the
variable with the reference to the object going out of scope). The
object was created, and the object is associated with a file, the
underlying file will also be closed.
-
-
-
=head2 newStream([OPTS])
Usage is
See the L</"Constructor Options"> section for more details.
-
=head2 deflateParams
Usage is
TODO
-
=head1 Importing
-
A number of symbolic constants are required by some methods in
C<IO::Compress::Gzip>. None are imported by default.
-
-
=over 5
=item :all
-
Imports C<gzip>, C<$GzipError> and all symbolic
constants that can be used by C<IO::Compress::Gzip>. Same as doing this
Import all symbolic constants. Same as doing this
-
use IO::Compress::Gzip qw(:flush :level :strategy) ;
-
=item :flush
These symbolic constants are used by the C<flush> method.
Z_BEST_COMPRESSION
Z_DEFAULT_COMPRESSION
-
=item :strategy
These symbolic constants are used by the C<Strategy> option in the constructor.
=back
-For
-
=head1 EXAMPLES
-TODO
-
-
-
-
-
-
+=head2 Apache::GZip Revisited
+See L<IO::Compress::Zlib::FAQ|IO::Compress::Zlib::FAQ/"Apache::GZip Revisited">
+
+=head2 Working with Net::FTP
+See L<IO::Compress::Zlib::FAQ|IO::Compress::Zlib::FAQ/"Compressed files and Net::FTP">
=head1 SEE ALSO
L<Archive::Tar|Archive::Tar>,
L<IO::Zlib|IO::Zlib>
-
For RFC 1950, 1951 and 1952 see
F<http://www.faqs.org/rfcs/rfc1950.html>,
F<http://www.faqs.org/rfcs/rfc1951.html> and
The primary site for gzip is F<http://www.gzip.org>.
-
-
-
=head1 AUTHOR
This module was written by Paul Marquess, F<pmqs@cpan.org>.
-
-
=head1 MODIFICATION HISTORY
See the Changes file.
=head1 COPYRIGHT AND LICENSE
-Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
+Copyright (c) 2005-2008 Paul Marquess. All rights reserved.
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
-
our ($VERSION, @ISA, @EXPORT, %GZIP_OS_Names);
our ($GZIP_FNAME_INVALID_CHAR_RE, $GZIP_FCOMMENT_INVALID_CHAR_RE);
-$VERSION = '2.008';
+$VERSION = '2.009';
@ISA = qw(Exporter);
use bytes;
-use IO::Compress::Base 2.008 ;
-use IO::Compress::Base::Common 2.008 qw(:Status createSelfTiedObject);
-use IO::Compress::Adapter::Deflate 2.008 ;
+use IO::Compress::Base 2.009 ;
+use IO::Compress::Base::Common 2.009 qw(:Status createSelfTiedObject);
+use IO::Compress::Adapter::Deflate 2.009 ;
require Exporter ;
our ($VERSION, @ISA, @EXPORT_OK, %DEFLATE_CONSTANTS, %EXPORT_TAGS, $RawDeflateError);
-$VERSION = '2.008';
+$VERSION = '2.009';
$RawDeflateError = '';
@ISA = qw(Exporter IO::Compress::Base);
{
my $self = shift ;
- use IO::Compress::Base::Common 2.008 qw(:Parse);
- use Compress::Raw::Zlib 2.008 qw(Z_DEFLATED Z_DEFAULT_COMPRESSION Z_DEFAULT_STRATEGY);
+ use IO::Compress::Base::Common 2.009 qw(:Parse);
+ use Compress::Raw::Zlib 2.009 qw(Z_DEFLATED Z_DEFAULT_COMPRESSION Z_DEFAULT_STRATEGY);
return (
=head1 NAME
-
-
IO::Compress::RawDeflate - Write RFC 1951 files/buffers
use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
-
my $status = rawdeflate $input => $output [,OPTS]
or die "rawdeflate failed: $RawDeflateError\n";
=head1 DESCRIPTION
-
This module provides a Perl interface that allows writing compressed
data to files or buffer as defined in RFC 1951.
-
-
-
-
-
-
Note that RFC 1951 data is not a good choice of compression format
to use in isolation, especially if you want to auto-detect it.
-
-
-
-
For reading RFC 1951 files/buffers, see the companion module
L<IO::Uncompress::RawInflate|IO::Uncompress::RawInflate>.
-
=head1 Functional Interface
A top-level function, C<rawdeflate>, is provided to carry out
rawdeflate $input => $output [,OPTS]
or die "rawdeflate failed: $RawDeflateError\n";
-
-
The functional interface needs Perl5.005 or better.
-
=head2 rawdeflate $input => $output [, OPTS]
-
C<rawdeflate> expects at least two parameters, C<$input> and C<$output>.
=head3 The C<$input> parameter
The complete array will be walked to ensure that it only
contains valid filenames before any data is compressed.
-
-
=item An Input FileGlob string
If C<$input> is a string that is delimited by the characters "<" and ">"
See L<File::GlobMapper|File::GlobMapper> for more details.
-
=back
If the C<$input> parameter is any other type, C<undef> will be returned.
-
-
=head3 The C<$output> parameter
The parameter C<$output> is used to control the destination of the
will be written to it.
The string '-' can be used as an alias for standard output.
-
=item A scalar reference
If C<$output> is a scalar reference, the compressed data will be
stored in C<$$output>.
-
-
=item An Array Reference
If C<$output> is an array reference, the compressed data will be
If the C<$output> parameter is any other type, C<undef> will be returned.
-
-
=head2 Notes
-
-
When C<$input> maps to multiple files/buffers and C<$output> is a single
file/buffer the input files/buffers will be stored
in C<$output> as a concatenated series of compressed data streams.
-
-
-
-
-
=head2 Optional Parameters
Unless specified below, the optional parameters for C<rawdeflate>,
This parameter defaults to 0.
-
=item C<< BinModeIn => 0|1 >>
When reading from a file or filehandle, set C<binmode> before reading.
Defaults to 0.
-
-
-
-
=item C<< Append => 0|1 >>
TODO
-
-
=back
-
-
=head2 Examples
To read the contents of the file C<file1.txt> and write the compressed
rawdeflate $input => "$input.1951"
or die "rawdeflate failed: $RawDeflateError\n";
-
To read from an existing Perl filehandle, C<$input>, and write the
compressed data to a buffer, C<$buffer>.
or die "Error compressing '$input': $RawDeflateError\n";
}
-
=head1 OO Interface
=head2 Constructor
written to it.
The string '-' can be used as an alias for standard output.
-
=item A scalar reference
If C<$output> is a scalar reference, the compressed data will be stored
This parameter defaults to 0.
-
-
-
-
=item C<< Merge => 0|1 >>
This option is used to compress input data and append it to an existing
compressed data stream in C<$output>. The end result is a single compressed
data stream stored in C<$output>.
-
-
It is a fatal error to attempt to use this option when C<$output> is not an
RFC 1951 data stream.
-
-
There are a number of other limitations with the C<Merge> option:
=over 5
=back
-
This parameter defaults to 0.
-
-
=item -Level
Defines the compression level used by zlib. The value should either be
The default is Z_DEFAULT_STRATEGY.
-
-
-
-
-
=item C<< Strict => 0|1 >>
-
-
This is a placeholder option.
-
-
=back
=head2 Examples
Usage is
-
$z->flush;
$z->flush($flush_type);
-
Flushes any pending compressed data to the output file/buffer.
-
This method takes an optional parameter, C<$flush_type>, that controls
how the flushing will be carried out. By default the C<$flush_type>
used is C<Z_FINISH>. Other valid values for C<$flush_type> are
can seriously degrade the level of compression achieved. See the C<zlib>
documentation for details.
-
Returns true on success.
-
=head2 tell
Usage is
$z->eof();
eof($z);
-
-
Returns true if the C<close> method has been called.
-
-
=head2 seek
$z->seek($position, $whence);
seek($z, $position, $whence);
-
-
-
Provides a sub-set of the C<seek> functionality, with the restriction
that it is only legal to seek forward in the output file/buffer.
It is a fatal error to attempt to seek backward.
Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
-
-
The C<$whence> parameter takes one the usual values, namely SEEK_SET,
SEEK_CUR or SEEK_END.
$z->input_line_number()
$z->input_line_number(EXPR)
-
This method always returns C<undef> when compressing.
-
-
=head2 fileno
$z->fileno()
fileno($z)
-If the C<$z> object is associated with a file or a filehandle, this method
-will return the underlying file descriptor.
+If the C<$z> object is associated with a file or a filehandle, C<fileno>
+will return the underlying file descriptor. Once the C<close> method is
+called C<fileno> will return C<undef>.
-If the C<$z> object is is associated with a buffer, this method will
-return undef.
+If the C<$z> object is is associated with a buffer, this method will return
+C<undef>.
=head2 close
$z->close() ;
close $z ;
-
-
Flushes any pending compressed data and then closes the output file/buffer.
-
-
For most versions of Perl this method will be automatically invoked if
the IO::Compress::RawDeflate object is destroyed (either explicitly or by the
variable with the reference to the object going out of scope). The
object was created, and the object is associated with a file, the
underlying file will also be closed.
-
-
-
=head2 newStream([OPTS])
Usage is
See the L</"Constructor Options"> section for more details.
-
=head2 deflateParams
Usage is
TODO
-
=head1 Importing
-
A number of symbolic constants are required by some methods in
C<IO::Compress::RawDeflate>. None are imported by default.
-
-
=over 5
=item :all
-
Imports C<rawdeflate>, C<$RawDeflateError> and all symbolic
constants that can be used by C<IO::Compress::RawDeflate>. Same as doing this
Import all symbolic constants. Same as doing this
-
use IO::Compress::RawDeflate qw(:flush :level :strategy) ;
-
=item :flush
These symbolic constants are used by the C<flush> method.
Z_BEST_COMPRESSION
Z_DEFAULT_COMPRESSION
-
=item :strategy
These symbolic constants are used by the C<Strategy> option in the constructor.
=back
-For
-
=head1 EXAMPLES
-TODO
-
-
-
-
-
-
+=head2 Apache::GZip Revisited
+See L<IO::Compress::Zlib::FAQ|IO::Compress::Zlib::FAQ/"Apache::GZip Revisited">
+
+=head2 Working with Net::FTP
+See L<IO::Compress::Zlib::FAQ|IO::Compress::Zlib::FAQ/"Compressed files and Net::FTP">
=head1 SEE ALSO
L<Archive::Tar|Archive::Tar>,
L<IO::Zlib|IO::Zlib>
-
For RFC 1950, 1951 and 1952 see
F<http://www.faqs.org/rfcs/rfc1950.html>,
F<http://www.faqs.org/rfcs/rfc1951.html> and
The primary site for gzip is F<http://www.gzip.org>.
-
-
-
=head1 AUTHOR
This module was written by Paul Marquess, F<pmqs@cpan.org>.
-
-
=head1 MODIFICATION HISTORY
See the Changes file.
=head1 COPYRIGHT AND LICENSE
-Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
+Copyright (c) 2005-2008 Paul Marquess. All rights reserved.
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
-
use warnings;
use bytes;
-use IO::Compress::Base::Common 2.008 qw(:Status createSelfTiedObject);
-use IO::Compress::RawDeflate 2.008 ;
-use IO::Compress::Adapter::Deflate 2.008 ;
-use IO::Compress::Adapter::Identity 2.008 ;
-use IO::Compress::Zlib::Extra 2.008 ;
-use IO::Compress::Zip::Constants 2.008 ;
+use IO::Compress::Base::Common 2.009 qw(:Status createSelfTiedObject);
+use IO::Compress::RawDeflate 2.009 ;
+use IO::Compress::Adapter::Deflate 2.009 ;
+use IO::Compress::Adapter::Identity 2.009 ;
+use IO::Compress::Zlib::Extra 2.009 ;
+use IO::Compress::Zip::Constants 2.009 ;
-use Compress::Raw::Zlib 2.008 qw(crc32) ;
+use Compress::Raw::Zlib 2.009 qw(crc32) ;
BEGIN
{
eval { require IO::Compress::Adapter::Bzip2 ;
- import IO::Compress::Adapter::Bzip2 2.008 ;
+ import IO::Compress::Adapter::Bzip2 2.009 ;
require IO::Compress::Bzip2 ;
- import IO::Compress::Bzip2 2.008 ;
+ import IO::Compress::Bzip2 2.009 ;
} ;
}
our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $ZipError);
-$VERSION = '2.008';
+$VERSION = '2.009';
$ZipError = '';
@ISA = qw(Exporter IO::Compress::RawDeflate);
my $empty = 0;
my $osCode = $param->value('OS_Code') ;
my $extFileAttr = 0 ;
+
+ # This code assumes Unix.
+ $extFileAttr = 0666 << 16
+ if $osCode == ZIP_OS_CODE_UNIX ;
if (*$self->{ZipData}{Zip64}) {
$empty = 0xFFFF;
$ctlExtra .= mkUnix2Extra();
}
- # TODO - this code assumes Unix.
- #$extFileAttr = 0666 << 16
- # if $osCode == ZIP_OS_CODE_UNIX ;
-
$extFileAttr = $param->value('ExtAttr')
if defined $param->value('ExtAttr') ;
$got->value("ATime", $timeRef->[0]);
$got->value("CTime", $timeRef->[2]);
}
+
+ # Unix2 Extended Attribute
+ if (! $got->parsed('exUnix2') ) {
+ my $timeRef = $got->value('exUnix2');
+ if ( defined $timeRef) {
+ return $self->saveErrorString(undef, "exUnix2 not a 2-element array ref")
+ if ref $timeRef ne 'ARRAY' || @$timeRef != 2;
+ }
+
+ $got->value("UID", $timeRef->[0]);
+ $got->value("GID", $timeRef->[1]);
+ }
*$self->{ZipData}{Zip64} = $got->value('Zip64');
*$self->{ZipData}{Stream} = $got->value('Stream');
{
my $self = shift ;
- use IO::Compress::Base::Common 2.008 qw(:Parse);
- use Compress::Raw::Zlib 2.008 qw(Z_DEFLATED Z_DEFAULT_COMPRESSION Z_DEFAULT_STRATEGY);
+ use IO::Compress::Base::Common 2.009 qw(:Parse);
+ use Compress::Raw::Zlib 2.009 qw(Z_DEFLATED Z_DEFAULT_COMPRESSION Z_DEFAULT_STRATEGY);
my @Bzip2 = ();
'Name' => [0, 1, Parse_any, ''],
'Time' => [0, 1, Parse_any, undef],
'exTime' => [0, 1, Parse_any, undef],
+ 'exUnix2' => [0, 1, Parse_any, undef],
'ExtAttr' => [0, 1, Parse_any, 0],
'OS_Code' => [0, 1, Parse_unsigned, $Compress::Raw::Zlib::gzip_os_code],
$params->value('CTime' => undef) ; # No Creation time
}
+ # NOTE - Unix specific code alert
$params->value('ExtAttr' => $mode << 16)
if ! $params->parsed('ExtAttr');
=head1 NAME
-
-
IO::Compress::Zip - Write zip files/buffers
use IO::Compress::Zip qw(zip $ZipError) ;
-
my $status = zip $input => $output [,OPTS]
or die "zip failed: $ZipError\n";
=head1 DESCRIPTION
-
This module provides a Perl interface that allows writing zip
compressed data to files or buffer.
-
-
-
-
-
-
-
-
The primary purpose of this module is to provide streaming write access to
zip files and buffers. It is not a general-purpose file archiver. If that
is what you want, check out C<Archive::Zip>.
Note that to create Bzip2 content, the module C<IO::Compress::Bzip2> must
be installed.
-
-
-
For reading zip files/buffers, see the companion module
L<IO::Uncompress::Unzip|IO::Uncompress::Unzip>.
-
=head1 Functional Interface
A top-level function, C<zip>, is provided to carry out
zip $input => $output [,OPTS]
or die "zip failed: $ZipError\n";
-
-
The functional interface needs Perl5.005 or better.
-
=head2 zip $input => $output [, OPTS]
-
C<zip> expects at least two parameters, C<$input> and C<$output>.
=head3 The C<$input> parameter
The complete array will be walked to ensure that it only
contains valid filenames before any data is compressed.
-
-
=item An Input FileGlob string
If C<$input> is a string that is delimited by the characters "<" and ">"
See L<File::GlobMapper|File::GlobMapper> for more details.
-
=back
If the C<$input> parameter is any other type, C<undef> will be returned.
-
In addition, if C<$input> is a simple filename, the default values for
the C<Name>, C<Time>, C<ExtAttr> and C<exTime> options will be sourced from that file.
explicitly setting the C<Name>, C<Time>, C<ExtAttr> and C<exTime> options or by setting the
C<Minimal> parameter.
-
-
=head3 The C<$output> parameter
The parameter C<$output> is used to control the destination of the
will be written to it.
The string '-' can be used as an alias for standard output.
-
=item A scalar reference
If C<$output> is a scalar reference, the compressed data will be
stored in C<$$output>.
-
-
=item An Array Reference
If C<$output> is an array reference, the compressed data will be
If the C<$output> parameter is any other type, C<undef> will be returned.
-
-
=head2 Notes
-
-
When C<$input> maps to multiple files/buffers and C<$output> is a single
file/buffer the input files/buffers will each be stored
in C<$output> as a distinct entry.
-
-
-
-
-
=head2 Optional Parameters
Unless specified below, the optional parameters for C<zip>,
This parameter defaults to 0.
-
=item C<< BinModeIn => 0|1 >>
When reading from a file or filehandle, set C<binmode> before reading.
Defaults to 0.
-
-
-
-
=item C<< Append => 0|1 >>
TODO
-
-
=back
-
-
=head2 Examples
To read the contents of the file C<file1.txt> and write the compressed
zip $input => "$input.zip"
or die "zip failed: $ZipError\n";
-
To read from an existing Perl filehandle, C<$input>, and write the
compressed data to a buffer, C<$buffer>.
or die "Error compressing '$input': $ZipError\n";
}
-
=head1 OO Interface
=head2 Constructor
written to it.
The string '-' can be used as an alias for standard output.
-
=item A scalar reference
If C<$output> is a scalar reference, the compressed data will be stored
This parameter defaults to 0.
-
-
=item C<< Name => $string >>
Stores the contents of C<$string> in the zip filename header field. If
This option controls the "external file attributes" field in the central
header of the zip file. This is a 4 byte field.
-This option defaults to 0.
+If you are running a Unix derivative this value defaults to
+
+ 0666 << 16
+
+This should allow read/write access to any files that are extracted from
+the zip file/buffer.
+
+For all other systems it defaults to 0.
=item C<< exTime => [$atime, $mtime, $ctime] >>
C<$atime>, C<mtime> and C<$ctime>. These correspond to the last access
time, last modification time and creation time respectively.
-It uses these values to set the extended timestamp field in the local zip
-header to the three values, $atime, $mtime, $ctime and sets the extended
-timestamp field in the central zip header to C<$mtime>.
+It uses these values to set the extended timestamp field (ID is "UT") in
+the local zip header using the three values, $atime, $mtime, $ctime. In
+addition it sets the extended timestamp field in the central zip header
+using C<$mtime>.
If any of the three values is C<undef> that time value will not be used.
So, for example, to set only the C<$mtime> you would use this
By default no extended time field is created.
+=item C<< exUnix2 => [$uid, $gid] >>
+
+This option expects an array reference with exactly two elements: C<$uid>
+and C<$gid>. These values correspond to the numeric user ID and group ID
+of the owner of the files respectively.
+
+When the C<exUnix2> option is present it will trigger the creation of a
+Unix2 extra field (ID is "Ux") in the local zip. This will be populated
+with C<$uid> and C<$gid>. In addition an empty Unix2 extra field will also
+be created in the central zip header
+
+If the C<Minimal> option is set to true, this option will be ignored.
+
+By default no Unix2 extra field is created.
+
=item C<< Comment => $comment >>
Stores the contents of C<$comment> in the Central File Header of
=item C<< ExtraFieldLocal => $data >>
=item C<< ExtraFieldCentral => $data >>
-These options allows additional metadata to be stored in the local and
-central headers in the zip file/buffer.
+The C<ExtraFieldLocal> option is used to store additional metadata in the
+local header for the zip file/buffer. The C<ExtraFieldCentral> does the
+same for the matching central header.
An extra field consists of zero or more subfields. Each subfield consists
of a two byte header followed by the subfield data.
ExtraField => $rawdata
-The Extended Time field, set using the C<exTime> option, is an example of
-an extended field.
-
-
+The Extended Time field (ID "UT"), set using the C<exTime> option, and the
+Unix2 extra field (ID "Ux), set using the C<exUnix2> option, are examples
+of extra fields.
If the C<Minimal> option is set to true, this option will be ignored.
=item C<< Minimal => 1|0 >>
-If specified, this option will disable the creation of all extended fields
-in the zip local and central headers. So the C<exTime>, C<ExtraFieldLocal>
-and C<ExtraFieldCentral> options will be ignored.
+If specified, this option will disable the creation of all extra fields
+in the zip local and central headers. So the C<exTime>, C<exUnix2>,
+C<ExtraFieldLocal> and C<ExtraFieldCentral> options will be ignored.
This parameter defaults to 0.
The default is 0.
-
-
-
=item -Level
Defines the compression level used by zlib. The value should either be
The default is Z_DEFAULT_STRATEGY.
-
-
-
-
-
=item C<< Strict => 0|1 >>
-
-
This is a placeholder option.
-
-
=back
=head2 Examples
Usage is
-
$z->flush;
$z->flush($flush_type);
-
Flushes any pending compressed data to the output file/buffer.
-
This method takes an optional parameter, C<$flush_type>, that controls
how the flushing will be carried out. By default the C<$flush_type>
used is C<Z_FINISH>. Other valid values for C<$flush_type> are
can seriously degrade the level of compression achieved. See the C<zlib>
documentation for details.
-
Returns true on success.
-
=head2 tell
Usage is
$z->eof();
eof($z);
-
-
Returns true if the C<close> method has been called.
-
-
=head2 seek
$z->seek($position, $whence);
seek($z, $position, $whence);
-
-
-
Provides a sub-set of the C<seek> functionality, with the restriction
that it is only legal to seek forward in the output file/buffer.
It is a fatal error to attempt to seek backward.
Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
-
-
The C<$whence> parameter takes one the usual values, namely SEEK_SET,
SEEK_CUR or SEEK_END.
$z->input_line_number()
$z->input_line_number(EXPR)
-
This method always returns C<undef> when compressing.
-
-
=head2 fileno
$z->fileno()
fileno($z)
-If the C<$z> object is associated with a file or a filehandle, this method
-will return the underlying file descriptor.
+If the C<$z> object is associated with a file or a filehandle, C<fileno>
+will return the underlying file descriptor. Once the C<close> method is
+called C<fileno> will return C<undef>.
-If the C<$z> object is is associated with a buffer, this method will
-return undef.
+If the C<$z> object is is associated with a buffer, this method will return
+C<undef>.
=head2 close
$z->close() ;
close $z ;
-
-
Flushes any pending compressed data and then closes the output file/buffer.
-
-
For most versions of Perl this method will be automatically invoked if
the IO::Compress::Zip object is destroyed (either explicitly or by the
variable with the reference to the object going out of scope). The
object was created, and the object is associated with a file, the
underlying file will also be closed.
-
-
-
=head2 newStream([OPTS])
Usage is
See the L</"Constructor Options"> section for more details.
-
=head2 deflateParams
Usage is
TODO
-
=head1 Importing
-
A number of symbolic constants are required by some methods in
C<IO::Compress::Zip>. None are imported by default.
-
-
=over 5
=item :all
-
Imports C<zip>, C<$ZipError> and all symbolic
constants that can be used by C<IO::Compress::Zip>. Same as doing this
Import all symbolic constants. Same as doing this
-
use IO::Compress::Zip qw(:flush :level :strategy :zip_method) ;
-
=item :flush
These symbolic constants are used by the C<flush> method.
Z_BEST_COMPRESSION
Z_DEFAULT_COMPRESSION
-
=item :strategy
These symbolic constants are used by the C<Strategy> option in the constructor.
Z_FIXED
Z_DEFAULT_STRATEGY
-
=item :zip_method
These symbolic constants are used by the C<Method> option in the
=back
-For
-
=head1 EXAMPLES
-TODO
-
-
-
-
-
-
+=head2 Apache::GZip Revisited
+See L<IO::Compress::Zlib::FAQ|IO::Compress::Zlib::FAQ/"Apache::GZip Revisited">
+
+=head2 Working with Net::FTP
+See L<IO::Compress::Zlib::FAQ|IO::Compress::Zlib::FAQ/"Compressed files and Net::FTP">
=head1 SEE ALSO
L<Archive::Tar|Archive::Tar>,
L<IO::Zlib|IO::Zlib>
-
For RFC 1950, 1951 and 1952 see
F<http://www.faqs.org/rfcs/rfc1950.html>,
F<http://www.faqs.org/rfcs/rfc1951.html> and
The primary site for gzip is F<http://www.gzip.org>.
-
-
-
=head1 AUTHOR
This module was written by Paul Marquess, F<pmqs@cpan.org>.
-
-
=head1 MODIFICATION HISTORY
See the Changes file.
=head1 COPYRIGHT AND LICENSE
-Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
+Copyright (c) 2005-2008 Paul Marquess. All rights reserved.
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
-
our ($VERSION, @ISA, @EXPORT, %ZIP_CM_MIN_VERSIONS);
-$VERSION = '2.008';
+$VERSION = '2.009';
@ISA = qw(Exporter);
ZIP_CM_DEFLATE
ZIP_CM_BZIP2
ZIP_CM_LZMA
+ ZIP_CM_PPMD
ZIP_LOCAL_HDR_SIG
ZIP_DATA_HDR_SIG
use constant ZIP_CM_DEFLATE => 8 ;
use constant ZIP_CM_BZIP2 => 12 ;
use constant ZIP_CM_LZMA => 14 ; # Not Supported yet
+use constant ZIP_CM_PPMD => 98 ; # Not Supported yet
# General Purpose Flag
-use constant ZIP_GP_FLAG_ENCRYPTED_MASK => 1 ;
-use constant ZIP_GP_FLAG_STREAMING_MASK => 8 ;
-use constant ZIP_GP_FLAG_PATCHED_MASK => 32 ;
-use constant ZIP_GP_FLAG_STRONG_ENCRYPTED_MASK => 64 ;
-use constant ZIP_GP_FLAG_LZMA_EOS_PRESENT => 2 ;
+use constant ZIP_GP_FLAG_ENCRYPTED_MASK => (1 << 0) ;
+use constant ZIP_GP_FLAG_STREAMING_MASK => (1 << 3) ;
+use constant ZIP_GP_FLAG_PATCHED_MASK => (1 << 5) ;
+use constant ZIP_GP_FLAG_STRONG_ENCRYPTED_MASK => (1 << 6) ;
+use constant ZIP_GP_FLAG_LZMA_EOS_PRESENT => (1 << 1) ;
+use constant ZIP_GP_FLAG_LANGUAGE_ENCODING => (1 << 11) ;
# Internal File Attributes
use constant ZIP_IFA_TEXT_MASK => 1;
our ($VERSION, @ISA, @EXPORT);
-$VERSION = '2.008';
+$VERSION = '2.009';
@ISA = qw(Exporter);
our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS);
-$VERSION = '2.008';
+$VERSION = '2.009';
-use IO::Compress::Gzip::Constants 2.008 ;
+use IO::Compress::Gzip::Constants 2.009 ;
sub ExtraFieldError
{
use strict;
use bytes;
-use IO::Compress::Base::Common 2.008 qw(:Status);
+use IO::Compress::Base::Common 2.009 qw(:Status);
our ($VERSION);
-$VERSION = '2.008';
+$VERSION = '2.009';
-use Compress::Raw::Zlib 2.008 ();
+use Compress::Raw::Zlib 2.009 ();
sub mkUncompObject
{
use warnings;
use bytes;
-use IO::Compress::Base::Common 2.008 qw(:Status);
-use Compress::Raw::Zlib 2.008 qw(Z_OK Z_DATA_ERROR Z_STREAM_END Z_FINISH MAX_WBITS);
+use IO::Compress::Base::Common 2.009 qw(:Status);
+use Compress::Raw::Zlib 2.009 qw(Z_OK Z_DATA_ERROR Z_STREAM_END Z_FINISH MAX_WBITS);
our ($VERSION);
-$VERSION = '2.008';
+$VERSION = '2.009';
use warnings;
use bytes;
-use IO::Compress::Base::Common 2.008 qw(createSelfTiedObject);
+use IO::Compress::Base::Common 2.009 qw(createSelfTiedObject);
-use IO::Uncompress::Adapter::Inflate 2.008 ();
+use IO::Uncompress::Adapter::Inflate 2.009 ();
-use IO::Uncompress::Base 2.008 ;
-use IO::Uncompress::Gunzip 2.008 ;
-use IO::Uncompress::Inflate 2.008 ;
-use IO::Uncompress::RawInflate 2.008 ;
-use IO::Uncompress::Unzip 2.008 ;
+use IO::Uncompress::Base 2.009 ;
+use IO::Uncompress::Gunzip 2.009 ;
+use IO::Uncompress::Inflate 2.009 ;
+use IO::Uncompress::RawInflate 2.009 ;
+use IO::Uncompress::Unzip 2.009 ;
require Exporter ;
our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $AnyInflateError);
-$VERSION = '2.008';
+$VERSION = '2.009';
$AnyInflateError = '';
@ISA = qw( Exporter IO::Uncompress::Base );
sub getExtraParams
{
- use IO::Compress::Base::Common 2.008 qw(:Parse);
+ use IO::Compress::Base::Common 2.009 qw(:Parse);
return ( 'RawInflate' => [1, 1, Parse_boolean, 0] ) ;
}
=head1 NAME
-
IO::Uncompress::AnyInflate - Uncompress zlib-based (zip, gzip) file/buffer
-
=head1 SYNOPSIS
use IO::Uncompress::AnyInflate qw(anyinflate $AnyInflateError) ;
eof($z)
close($z)
-
=head1 DESCRIPTION
-
This module provides a Perl interface that allows the reading of
files/buffers that have been compressed in a number of formats that use the
zlib compression library.
The module will auto-detect which, if any, of the supported
compression formats is being used.
-
-
-
-
=head1 Functional Interface
A top-level function, C<anyinflate>, is provided to carry out
anyinflate $input => $output [,OPTS]
or die "anyinflate failed: $AnyInflateError\n";
-
-
The functional interface needs Perl5.005 or better.
-
=head2 anyinflate $input => $output [, OPTS]
-
C<anyinflate> expects at least two parameters, C<$input> and C<$output>.
=head3 The C<$input> parameter
The complete array will be walked to ensure that it only
contains valid filenames before any data is uncompressed.
-
-
=item An Input FileGlob string
If C<$input> is a string that is delimited by the characters "<" and ">"
See L<File::GlobMapper|File::GlobMapper> for more details.
-
=back
If the C<$input> parameter is any other type, C<undef> will be returned.
-
-
=head3 The C<$output> parameter
The parameter C<$output> is used to control the destination of the
will be written to it.
The string '-' can be used as an alias for standard output.
-
=item A scalar reference
If C<$output> is a scalar reference, the uncompressed data will be
stored in C<$$output>.
-
-
=item An Array Reference
If C<$output> is an array reference, the uncompressed data will be
If the C<$output> parameter is any other type, C<undef> will be returned.
-
-
=head2 Notes
-
When C<$input> maps to multiple compressed files/buffers and C<$output> is
a single file/buffer, after uncompression C<$output> will contain a
concatenation of all the uncompressed data from each of the input
files/buffers.
-
-
-
-
=head2 Optional Parameters
Unless specified below, the optional parameters for C<anyinflate>,
This parameter defaults to 0.
-
=item C<< BinModeOut => 0|1 >>
When writing to a file or filehandle, set C<binmode> before writing to the
Defaults to 0.
-
-
-
-
=item C<< Append => 0|1 >>
TODO
=item C<< MultiStream => 0|1 >>
-
If the input file/buffer contains multiple compressed data streams, this
option will uncompress the whole lot as a single data stream.
Defaults to 0.
-
-
-
-
=item C<< TrailingData => $scalar >>
Returns the data, if any, that is present immediately after the compressed
Don't bother using C<trailingData> if the input is a filename.
-
-
If you know the length of the compressed data stream before you start
uncompressing, you can avoid having to use C<trailingData> by setting the
C<InputLength> option.
-
-
=back
-
-
-
=head2 Examples
To read the contents of the file C<file1.txt.Compressed> and write the
anyinflate $input => $output
or die "anyinflate failed: $AnyInflateError\n";
-
To read from an existing Perl filehandle, C<$input>, and write the
uncompressed data to a buffer, C<$buffer>.
The format of the constructor for IO::Uncompress::AnyInflate is shown below
-
my $z = new IO::Uncompress::AnyInflate $input [OPTS]
or die "IO::Uncompress::AnyInflate failed: $AnyInflateError\n";
read from it.
The string '-' can be used as an alias for standard input.
-
=item A scalar reference
If C<$input> is a scalar reference, the compressed data will be read from
=head2 Constructor Options
-
The option names defined below are case insensitive and can be optionally
prefixed by a '-'. So all of the following are valid
=item C<< MultiStream => 0|1 >>
-
-
Allows multiple concatenated compressed streams to be treated as a single
compressed stream. Decompression will stop once either the end of the
file/buffer is reached, an error is encountered (premature eof, corrupt
This parameter defaults to 0.
-
=item C<< Prime => $string >>
This option will uncompress the contents of C<$string> before processing the
the file pointer will be left pointing to the first byte directly after the
compressed data stream.
-
-
This option defaults to off.
=item C<< Append => 0|1 >>
=item C<< Strict => 0|1 >>
-
-
This option controls whether the extra checks defined below are used when
carrying out the decompression. When Strict is on, the extra tests are
carried out, when Strict is off they are not.
The default for this option is off.
-
If the input is an RFC 1950 data stream, the following will be checked:
-
-
-
=over 5
=item 1
=back
-
-
If the input is a gzip (RFC 1952) data stream, the following will be checked:
-
-
-
=over 5
=item 1
=back
-
-
-
-
=item C<< RawInflate => 0|1 >>
When auto-detecting the compressed format, try to test for raw-deflate (RFC
Defaults to 0.
-
-
-
=item C<< ParseExtra => 0|1 >>
If the gzip FEXTRA header field is present and this option is set, it will
force the module to check that it conforms to the sub-field structure as
Defaults to 0.
-
-
-
=back
=head2 Examples
Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
or a negative number on error.
-
=head2 getline
Usage is
determine what constitutes an end of line. Paragraph mode, record mode and
file slurp mode are all supported.
-
=head2 getc
Usage is
$char = $z->ungetc($string)
-
-
=head2 inflateSync
Usage is
TODO
-
=head2 getHeaderInfo
Usage is
or hash references (in array context) that contains information about each
of the header fields in the compressed data stream(s).
-
-
-
=head2 tell
Usage is
$z->eof();
eof($z);
-
-
Returns true if the end of the compressed input stream has been reached.
-
-
=head2 seek
$z->seek($position, $whence);
seek($z, $position, $whence);
-
-
-
Provides a sub-set of the C<seek> functionality, with the restriction
that it is only legal to seek forward in the input file/buffer.
It is a fatal error to attempt to seek backward.
-
-
The C<$whence> parameter takes one the usual values, namely SEEK_SET,
SEEK_CUR or SEEK_END.
$z->input_line_number()
$z->input_line_number(EXPR)
-
-
Returns the current uncompressed line number. If C<EXPR> is present it has
the effect of setting the line number. Note that setting the line number
does not change the current position within the file/buffer being read.
The contents of C<$/> are used to to determine what constitutes a line
terminator.
-
-
=head2 fileno
$z->fileno()
fileno($z)
-If the C<$z> object is associated with a file or a filehandle, this method
-will return the underlying file descriptor.
+If the C<$z> object is associated with a file or a filehandle, C<fileno>
+will return the underlying file descriptor. Once the C<close> method is
+called C<fileno> will return C<undef>.
-If the C<$z> object is is associated with a buffer, this method will
-return undef.
+If the C<$z> object is is associated with a buffer, this method will return
+C<undef>.
=head2 close
$z->close() ;
close $z ;
-
-
Closes the output file/buffer.
-
-
For most versions of Perl this method will be automatically invoked if
the IO::Uncompress::AnyInflate object is destroyed (either explicitly or by the
variable with the reference to the object going out of scope). The
object was created, and the object is associated with a file, the
underlying file will also be closed.
-
-
-
=head2 nextStream
Usage is
Don't bother using C<trailingData> if the input is a filename.
-
-
If you know the length of the compressed data stream before you start
uncompressing, you can avoid having to use C<trailingData> by setting the
C<InputLength> option in the constructor.
=head1 EXAMPLES
+=head2 Working with Net::FTP
-
+See L<IO::Uncompress::AnyInflate::FAQ|IO::Uncompress::AnyInflate::FAQ/"Compressed files and Net::FTP">
=head1 SEE ALSO
L<Archive::Tar|Archive::Tar>,
L<IO::Zlib|IO::Zlib>
-
For RFC 1950, 1951 and 1952 see
F<http://www.faqs.org/rfcs/rfc1950.html>,
F<http://www.faqs.org/rfcs/rfc1951.html> and
The primary site for gzip is F<http://www.gzip.org>.
-
-
-
=head1 AUTHOR
This module was written by Paul Marquess, F<pmqs@cpan.org>.
-
-
=head1 MODIFICATION HISTORY
See the Changes file.
=head1 COPYRIGHT AND LICENSE
-Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
+Copyright (c) 2005-2008 Paul Marquess. All rights reserved.
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
use warnings;
use bytes;
-use IO::Uncompress::RawInflate 2.008 ;
+use IO::Uncompress::RawInflate 2.009 ;
-use Compress::Raw::Zlib 2.008 qw( crc32 ) ;
-use IO::Compress::Base::Common 2.008 qw(:Status createSelfTiedObject);
-use IO::Compress::Gzip::Constants 2.008 ;
-use IO::Compress::Zlib::Extra 2.008 ;
+use Compress::Raw::Zlib 2.009 qw( crc32 ) ;
+use IO::Compress::Base::Common 2.009 qw(:Status createSelfTiedObject);
+use IO::Compress::Gzip::Constants 2.009 ;
+use IO::Compress::Zlib::Extra 2.009 ;
require Exporter ;
$GunzipError = '';
-$VERSION = '2.008';
+$VERSION = '2.009';
sub new
{
sub getExtraParams
{
- use IO::Compress::Base::Common 2.008 qw(:Parse);
+ use IO::Compress::Base::Common 2.009 qw(:Parse);
return ( 'ParseExtra' => [1, 1, Parse_boolean, 0] ) ;
}
=head1 NAME
-
-
IO::Uncompress::Gunzip - Read RFC 1952 files/buffers
-
-
=head1 SYNOPSIS
use IO::Uncompress::Gunzip qw(gunzip $GunzipError) ;
eof($z)
close($z)
-
=head1 DESCRIPTION
-
-
This module provides a Perl interface that allows the reading of
files/buffers that conform to RFC 1952.
For writing RFC 1952 files/buffers, see the companion module IO::Compress::Gzip.
-
-
-
-
=head1 Functional Interface
A top-level function, C<gunzip>, is provided to carry out
gunzip $input => $output [,OPTS]
or die "gunzip failed: $GunzipError\n";
-
-
The functional interface needs Perl5.005 or better.
-
=head2 gunzip $input => $output [, OPTS]
-
C<gunzip> expects at least two parameters, C<$input> and C<$output>.
=head3 The C<$input> parameter
The complete array will be walked to ensure that it only
contains valid filenames before any data is uncompressed.
-
-
=item An Input FileGlob string
If C<$input> is a string that is delimited by the characters "<" and ">"
See L<File::GlobMapper|File::GlobMapper> for more details.
-
=back
If the C<$input> parameter is any other type, C<undef> will be returned.
-
-
=head3 The C<$output> parameter
The parameter C<$output> is used to control the destination of the
will be written to it.
The string '-' can be used as an alias for standard output.
-
=item A scalar reference
If C<$output> is a scalar reference, the uncompressed data will be
stored in C<$$output>.
-
-
=item An Array Reference
If C<$output> is an array reference, the uncompressed data will be
If the C<$output> parameter is any other type, C<undef> will be returned.
-
-
=head2 Notes
-
When C<$input> maps to multiple compressed files/buffers and C<$output> is
a single file/buffer, after uncompression C<$output> will contain a
concatenation of all the uncompressed data from each of the input
files/buffers.
-
-
-
-
=head2 Optional Parameters
Unless specified below, the optional parameters for C<gunzip>,
This parameter defaults to 0.
-
=item C<< BinModeOut => 0|1 >>
When writing to a file or filehandle, set C<binmode> before writing to the
Defaults to 0.
-
-
-
-
=item C<< Append => 0|1 >>
TODO
=item C<< MultiStream => 0|1 >>
-
If the input file/buffer contains multiple compressed data streams, this
option will uncompress the whole lot as a single data stream.
Defaults to 0.
-
-
-
-
=item C<< TrailingData => $scalar >>
Returns the data, if any, that is present immediately after the compressed
Don't bother using C<trailingData> if the input is a filename.
-
-
If you know the length of the compressed data stream before you start
uncompressing, you can avoid having to use C<trailingData> by setting the
C<InputLength> option.
-
-
=back
-
-
-
=head2 Examples
To read the contents of the file C<file1.txt.gz> and write the
gunzip $input => $output
or die "gunzip failed: $GunzipError\n";
-
To read from an existing Perl filehandle, C<$input>, and write the
uncompressed data to a buffer, C<$buffer>.
The format of the constructor for IO::Uncompress::Gunzip is shown below
-
my $z = new IO::Uncompress::Gunzip $input [OPTS]
or die "IO::Uncompress::Gunzip failed: $GunzipError\n";
read from it.
The string '-' can be used as an alias for standard input.
-
=item A scalar reference
If C<$input> is a scalar reference, the compressed data will be read from
=head2 Constructor Options
-
The option names defined below are case insensitive and can be optionally
prefixed by a '-'. So all of the following are valid
=item C<< MultiStream => 0|1 >>
-
-
Allows multiple concatenated compressed streams to be treated as a single
compressed stream. Decompression will stop once either the end of the
file/buffer is reached, an error is encountered (premature eof, corrupt
This parameter defaults to 0.
-
=item C<< Prime => $string >>
This option will uncompress the contents of C<$string> before processing the
the file pointer will be left pointing to the first byte directly after the
compressed data stream.
-
-
This option defaults to off.
=item C<< Append => 0|1 >>
=item C<< Strict => 0|1 >>
-
-
This option controls whether the extra checks defined below are used when
carrying out the decompression. When Strict is on, the extra tests are
carried out, when Strict is off they are not.
The default for this option is off.
-
-
-
-
-
-
-
-
=over 5
=item 1
=back
-
-
-
-
-
-
=item C<< ParseExtra => 0|1 >>
If the gzip FEXTRA header field is present and this option is set, it will
force the module to check that it conforms to the sub-field structure as
Defaults to 0.
-
-
-
=back
=head2 Examples
Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
or a negative number on error.
-
=head2 getline
Usage is
determine what constitutes an end of line. Paragraph mode, record mode and
file slurp mode are all supported.
-
=head2 getc
Usage is
$char = $z->ungetc($string)
-
-
=head2 inflateSync
Usage is
TODO
-
=head2 getHeaderInfo
Usage is
or hash references (in array context) that contains information about each
of the header fields in the compressed data stream(s).
-
-
=over 5
=item Name
=back
-
-
-
=head2 tell
Usage is
$z->eof();
eof($z);
-
-
Returns true if the end of the compressed input stream has been reached.
-
-
=head2 seek
$z->seek($position, $whence);
seek($z, $position, $whence);
-
-
-
Provides a sub-set of the C<seek> functionality, with the restriction
that it is only legal to seek forward in the input file/buffer.
It is a fatal error to attempt to seek backward.
-
-
The C<$whence> parameter takes one the usual values, namely SEEK_SET,
SEEK_CUR or SEEK_END.
$z->input_line_number()
$z->input_line_number(EXPR)
-
-
Returns the current uncompressed line number. If C<EXPR> is present it has
the effect of setting the line number. Note that setting the line number
does not change the current position within the file/buffer being read.
The contents of C<$/> are used to to determine what constitutes a line
terminator.
-
-
=head2 fileno
$z->fileno()
fileno($z)
-If the C<$z> object is associated with a file or a filehandle, this method
-will return the underlying file descriptor.
+If the C<$z> object is associated with a file or a filehandle, C<fileno>
+will return the underlying file descriptor. Once the C<close> method is
+called C<fileno> will return C<undef>.
-If the C<$z> object is is associated with a buffer, this method will
-return undef.
+If the C<$z> object is is associated with a buffer, this method will return
+C<undef>.
=head2 close
$z->close() ;
close $z ;
-
-
Closes the output file/buffer.
-
-
For most versions of Perl this method will be automatically invoked if
the IO::Uncompress::Gunzip object is destroyed (either explicitly or by the
variable with the reference to the object going out of scope). The
object was created, and the object is associated with a file, the
underlying file will also be closed.
-
-
-
=head2 nextStream
Usage is
Don't bother using C<trailingData> if the input is a filename.
-
-
If you know the length of the compressed data stream before you start
uncompressing, you can avoid having to use C<trailingData> by setting the
C<InputLength> option in the constructor.
=head1 EXAMPLES
+=head2 Working with Net::FTP
-
+See L<IO::Uncompress::Gunzip::FAQ|IO::Uncompress::Gunzip::FAQ/"Compressed files and Net::FTP">
=head1 SEE ALSO
L<Archive::Tar|Archive::Tar>,
L<IO::Zlib|IO::Zlib>
-
For RFC 1950, 1951 and 1952 see
F<http://www.faqs.org/rfcs/rfc1950.html>,
F<http://www.faqs.org/rfcs/rfc1951.html> and
The primary site for gzip is F<http://www.gzip.org>.
-
-
-
=head1 AUTHOR
This module was written by Paul Marquess, F<pmqs@cpan.org>.
-
-
=head1 MODIFICATION HISTORY
See the Changes file.
=head1 COPYRIGHT AND LICENSE
-Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
+Copyright (c) 2005-2008 Paul Marquess. All rights reserved.
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
use warnings;
use bytes;
-use IO::Compress::Base::Common 2.008 qw(:Status createSelfTiedObject);
-use IO::Compress::Zlib::Constants 2.008 ;
+use IO::Compress::Base::Common 2.009 qw(:Status createSelfTiedObject);
+use IO::Compress::Zlib::Constants 2.009 ;
-use IO::Uncompress::RawInflate 2.008 ;
+use IO::Uncompress::RawInflate 2.009 ;
require Exporter ;
our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $InflateError);
-$VERSION = '2.008';
+$VERSION = '2.009';
$InflateError = '';
@ISA = qw( Exporter IO::Uncompress::RawInflate );
=head1 NAME
-
-
IO::Uncompress::Inflate - Read RFC 1950 files/buffers
-
-
=head1 SYNOPSIS
use IO::Uncompress::Inflate qw(inflate $InflateError) ;
eof($z)
close($z)
-
=head1 DESCRIPTION
-
-
This module provides a Perl interface that allows the reading of
files/buffers that conform to RFC 1950.
For writing RFC 1950 files/buffers, see the companion module IO::Compress::Deflate.
-
-
-
-
=head1 Functional Interface
A top-level function, C<inflate>, is provided to carry out
inflate $input => $output [,OPTS]
or die "inflate failed: $InflateError\n";
-
-
The functional interface needs Perl5.005 or better.
-
=head2 inflate $input => $output [, OPTS]
-
C<inflate> expects at least two parameters, C<$input> and C<$output>.
=head3 The C<$input> parameter
The complete array will be walked to ensure that it only
contains valid filenames before any data is uncompressed.
-
-
=item An Input FileGlob string
If C<$input> is a string that is delimited by the characters "<" and ">"
See L<File::GlobMapper|File::GlobMapper> for more details.
-
=back
If the C<$input> parameter is any other type, C<undef> will be returned.
-
-
=head3 The C<$output> parameter
The parameter C<$output> is used to control the destination of the
will be written to it.
The string '-' can be used as an alias for standard output.
-
=item A scalar reference
If C<$output> is a scalar reference, the uncompressed data will be
stored in C<$$output>.
-
-
=item An Array Reference
If C<$output> is an array reference, the uncompressed data will be
If the C<$output> parameter is any other type, C<undef> will be returned.
-
-
=head2 Notes
-
When C<$input> maps to multiple compressed files/buffers and C<$output> is
a single file/buffer, after uncompression C<$output> will contain a
concatenation of all the uncompressed data from each of the input
files/buffers.
-
-
-
-
=head2 Optional Parameters
Unless specified below, the optional parameters for C<inflate>,
This parameter defaults to 0.
-
=item C<< BinModeOut => 0|1 >>
When writing to a file or filehandle, set C<binmode> before writing to the
Defaults to 0.
-
-
-
-
=item C<< Append => 0|1 >>
TODO
=item C<< MultiStream => 0|1 >>
-
If the input file/buffer contains multiple compressed data streams, this
option will uncompress the whole lot as a single data stream.
Defaults to 0.
-
-
-
-
=item C<< TrailingData => $scalar >>
Returns the data, if any, that is present immediately after the compressed
Don't bother using C<trailingData> if the input is a filename.
-
-
If you know the length of the compressed data stream before you start
uncompressing, you can avoid having to use C<trailingData> by setting the
C<InputLength> option.
-
-
=back
-
-
-
=head2 Examples
To read the contents of the file C<file1.txt.1950> and write the
inflate $input => $output
or die "inflate failed: $InflateError\n";
-
To read from an existing Perl filehandle, C<$input>, and write the
uncompressed data to a buffer, C<$buffer>.
The format of the constructor for IO::Uncompress::Inflate is shown below
-
my $z = new IO::Uncompress::Inflate $input [OPTS]
or die "IO::Uncompress::Inflate failed: $InflateError\n";
read from it.
The string '-' can be used as an alias for standard input.
-
=item A scalar reference
If C<$input> is a scalar reference, the compressed data will be read from
=head2 Constructor Options
-
The option names defined below are case insensitive and can be optionally
prefixed by a '-'. So all of the following are valid
=item C<< MultiStream => 0|1 >>
-
-
Allows multiple concatenated compressed streams to be treated as a single
compressed stream. Decompression will stop once either the end of the
file/buffer is reached, an error is encountered (premature eof, corrupt
This parameter defaults to 0.
-
=item C<< Prime => $string >>
This option will uncompress the contents of C<$string> before processing the
the file pointer will be left pointing to the first byte directly after the
compressed data stream.
-
-
This option defaults to off.
=item C<< Append => 0|1 >>
=item C<< Strict => 0|1 >>
-
-
This option controls whether the extra checks defined below are used when
carrying out the decompression. When Strict is on, the extra tests are
carried out, when Strict is off they are not.
The default for this option is off.
-
-
-
-
=over 5
=item 1
=back
-
-
-
-
-
-
-
-
-
-
-
=back
=head2 Examples
Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
or a negative number on error.
-
=head2 getline
Usage is
determine what constitutes an end of line. Paragraph mode, record mode and
file slurp mode are all supported.
-
=head2 getc
Usage is
$char = $z->ungetc($string)
-
-
=head2 inflateSync
Usage is
TODO
-
=head2 getHeaderInfo
Usage is
or hash references (in array context) that contains information about each
of the header fields in the compressed data stream(s).
-
-
-
=head2 tell
Usage is
$z->eof();
eof($z);
-
-
Returns true if the end of the compressed input stream has been reached.
-
-
=head2 seek
$z->seek($position, $whence);
seek($z, $position, $whence);
-
-
-
Provides a sub-set of the C<seek> functionality, with the restriction
that it is only legal to seek forward in the input file/buffer.
It is a fatal error to attempt to seek backward.
-
-
The C<$whence> parameter takes one the usual values, namely SEEK_SET,
SEEK_CUR or SEEK_END.
$z->input_line_number()
$z->input_line_number(EXPR)
-
-
Returns the current uncompressed line number. If C<EXPR> is present it has
the effect of setting the line number. Note that setting the line number
does not change the current position within the file/buffer being read.
The contents of C<$/> are used to to determine what constitutes a line
terminator.
-
-
=head2 fileno
$z->fileno()
fileno($z)
-If the C<$z> object is associated with a file or a filehandle, this method
-will return the underlying file descriptor.
+If the C<$z> object is associated with a file or a filehandle, C<fileno>
+will return the underlying file descriptor. Once the C<close> method is
+called C<fileno> will return C<undef>.
-If the C<$z> object is is associated with a buffer, this method will
-return undef.
+If the C<$z> object is is associated with a buffer, this method will return
+C<undef>.
=head2 close
$z->close() ;
close $z ;
-
-
Closes the output file/buffer.
-
-
For most versions of Perl this method will be automatically invoked if
the IO::Uncompress::Inflate object is destroyed (either explicitly or by the
variable with the reference to the object going out of scope). The
object was created, and the object is associated with a file, the
underlying file will also be closed.
-
-
-
=head2 nextStream
Usage is
Don't bother using C<trailingData> if the input is a filename.
-
-
If you know the length of the compressed data stream before you start
uncompressing, you can avoid having to use C<trailingData> by setting the
C<InputLength> option in the constructor.
=head1 EXAMPLES
+=head2 Working with Net::FTP
-
+See L<IO::Uncompress::Inflate::FAQ|IO::Uncompress::Inflate::FAQ/"Compressed files and Net::FTP">
=head1 SEE ALSO
L<Archive::Tar|Archive::Tar>,
L<IO::Zlib|IO::Zlib>
-
For RFC 1950, 1951 and 1952 see
F<http://www.faqs.org/rfcs/rfc1950.html>,
F<http://www.faqs.org/rfcs/rfc1951.html> and
The primary site for gzip is F<http://www.gzip.org>.
-
-
-
=head1 AUTHOR
This module was written by Paul Marquess, F<pmqs@cpan.org>.
-
-
=head1 MODIFICATION HISTORY
See the Changes file.
=head1 COPYRIGHT AND LICENSE
-Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
+Copyright (c) 2005-2008 Paul Marquess. All rights reserved.
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
use warnings;
use bytes;
-use Compress::Raw::Zlib 2.008 ;
-use IO::Compress::Base::Common 2.008 qw(:Status createSelfTiedObject);
+use Compress::Raw::Zlib 2.009 ;
+use IO::Compress::Base::Common 2.009 qw(:Status createSelfTiedObject);
-use IO::Uncompress::Base 2.008 ;
-use IO::Uncompress::Adapter::Inflate 2.008 ;
+use IO::Uncompress::Base 2.009 ;
+use IO::Uncompress::Adapter::Inflate 2.009 ;
require Exporter ;
our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, %DEFLATE_CONSTANTS, $RawInflateError);
-$VERSION = '2.008';
+$VERSION = '2.009';
$RawInflateError = '';
@ISA = qw( Exporter IO::Uncompress::Base );
=head1 NAME
-
-
IO::Uncompress::RawInflate - Read RFC 1951 files/buffers
-
-
=head1 SYNOPSIS
use IO::Uncompress::RawInflate qw(rawinflate $RawInflateError) ;
eof($z)
close($z)
-
=head1 DESCRIPTION
-
-
This module provides a Perl interface that allows the reading of
files/buffers that conform to RFC 1951.
For writing RFC 1951 files/buffers, see the companion module IO::Compress::RawDeflate.
-
-
-
-
=head1 Functional Interface
A top-level function, C<rawinflate>, is provided to carry out
rawinflate $input => $output [,OPTS]
or die "rawinflate failed: $RawInflateError\n";
-
-
The functional interface needs Perl5.005 or better.
-
=head2 rawinflate $input => $output [, OPTS]
-
C<rawinflate> expects at least two parameters, C<$input> and C<$output>.
=head3 The C<$input> parameter
The complete array will be walked to ensure that it only
contains valid filenames before any data is uncompressed.
-
-
=item An Input FileGlob string
If C<$input> is a string that is delimited by the characters "<" and ">"
See L<File::GlobMapper|File::GlobMapper> for more details.
-
=back
If the C<$input> parameter is any other type, C<undef> will be returned.
-
-
=head3 The C<$output> parameter
The parameter C<$output> is used to control the destination of the
will be written to it.
The string '-' can be used as an alias for standard output.
-
=item A scalar reference
If C<$output> is a scalar reference, the uncompressed data will be
stored in C<$$output>.
-
-
=item An Array Reference
If C<$output> is an array reference, the uncompressed data will be
If the C<$output> parameter is any other type, C<undef> will be returned.
-
-
=head2 Notes
-
When C<$input> maps to multiple compressed files/buffers and C<$output> is
a single file/buffer, after uncompression C<$output> will contain a
concatenation of all the uncompressed data from each of the input
files/buffers.
-
-
-
-
=head2 Optional Parameters
Unless specified below, the optional parameters for C<rawinflate>,
This parameter defaults to 0.
-
=item C<< BinModeOut => 0|1 >>
When writing to a file or filehandle, set C<binmode> before writing to the
Defaults to 0.
-
-
-
-
=item C<< Append => 0|1 >>
TODO
=item C<< MultiStream => 0|1 >>
-
-
This option is a no-op.
-
-
-
-
=item C<< TrailingData => $scalar >>
Returns the data, if any, that is present immediately after the compressed
Don't bother using C<trailingData> if the input is a filename.
-
-
If you know the length of the compressed data stream before you start
uncompressing, you can avoid having to use C<trailingData> by setting the
C<InputLength> option.
-
-
=back
-
-
-
=head2 Examples
To read the contents of the file C<file1.txt.1951> and write the
rawinflate $input => $output
or die "rawinflate failed: $RawInflateError\n";
-
To read from an existing Perl filehandle, C<$input>, and write the
uncompressed data to a buffer, C<$buffer>.
The format of the constructor for IO::Uncompress::RawInflate is shown below
-
my $z = new IO::Uncompress::RawInflate $input [OPTS]
or die "IO::Uncompress::RawInflate failed: $RawInflateError\n";
read from it.
The string '-' can be used as an alias for standard input.
-
=item A scalar reference
If C<$input> is a scalar reference, the compressed data will be read from
=head2 Constructor Options
-
The option names defined below are case insensitive and can be optionally
prefixed by a '-'. So all of the following are valid
=item C<< MultiStream => 0|1 >>
-
-
Allows multiple concatenated compressed streams to be treated as a single
compressed stream. Decompression will stop once either the end of the
file/buffer is reached, an error is encountered (premature eof, corrupt
This parameter defaults to 0.
-
=item C<< Prime => $string >>
This option will uncompress the contents of C<$string> before processing the
the file pointer will be left pointing to the first byte directly after the
compressed data stream.
-
-
This option defaults to off.
=item C<< Append => 0|1 >>
=item C<< Strict => 0|1 >>
-
-
This option is a no-op.
-
-
-
-
-
-
=back
=head2 Examples
Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
or a negative number on error.
-
=head2 getline
Usage is
determine what constitutes an end of line. Paragraph mode, record mode and
file slurp mode are all supported.
-
=head2 getc
Usage is
$char = $z->ungetc($string)
-
-
=head2 inflateSync
Usage is
TODO
-
=head2 getHeaderInfo
Usage is
or hash references (in array context) that contains information about each
of the header fields in the compressed data stream(s).
-
-
-
=head2 tell
Usage is
$z->eof();
eof($z);
-
-
Returns true if the end of the compressed input stream has been reached.
-
-
=head2 seek
$z->seek($position, $whence);
seek($z, $position, $whence);
-
-
-
Provides a sub-set of the C<seek> functionality, with the restriction
that it is only legal to seek forward in the input file/buffer.
It is a fatal error to attempt to seek backward.
-
-
The C<$whence> parameter takes one the usual values, namely SEEK_SET,
SEEK_CUR or SEEK_END.
$z->input_line_number()
$z->input_line_number(EXPR)
-
-
Returns the current uncompressed line number. If C<EXPR> is present it has
the effect of setting the line number. Note that setting the line number
does not change the current position within the file/buffer being read.
The contents of C<$/> are used to to determine what constitutes a line
terminator.
-
-
=head2 fileno
$z->fileno()
fileno($z)
-If the C<$z> object is associated with a file or a filehandle, this method
-will return the underlying file descriptor.
+If the C<$z> object is associated with a file or a filehandle, C<fileno>
+will return the underlying file descriptor. Once the C<close> method is
+called C<fileno> will return C<undef>.
-If the C<$z> object is is associated with a buffer, this method will
-return undef.
+If the C<$z> object is is associated with a buffer, this method will return
+C<undef>.
=head2 close
$z->close() ;
close $z ;
-
-
Closes the output file/buffer.
-
-
For most versions of Perl this method will be automatically invoked if
the IO::Uncompress::RawInflate object is destroyed (either explicitly or by the
variable with the reference to the object going out of scope). The
object was created, and the object is associated with a file, the
underlying file will also be closed.
-
-
-
=head2 nextStream
Usage is
Don't bother using C<trailingData> if the input is a filename.
-
-
If you know the length of the compressed data stream before you start
uncompressing, you can avoid having to use C<trailingData> by setting the
C<InputLength> option in the constructor.
=head1 EXAMPLES
+=head2 Working with Net::FTP
-
+See L<IO::Uncompress::RawInflate::FAQ|IO::Uncompress::RawInflate::FAQ/"Compressed files and Net::FTP">
=head1 SEE ALSO
L<Archive::Tar|Archive::Tar>,
L<IO::Zlib|IO::Zlib>
-
For RFC 1950, 1951 and 1952 see
F<http://www.faqs.org/rfcs/rfc1950.html>,
F<http://www.faqs.org/rfcs/rfc1951.html> and
The primary site for gzip is F<http://www.gzip.org>.
-
-
-
=head1 AUTHOR
This module was written by Paul Marquess, F<pmqs@cpan.org>.
-
-
=head1 MODIFICATION HISTORY
See the Changes file.
=head1 COPYRIGHT AND LICENSE
-Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
+Copyright (c) 2005-2008 Paul Marquess. All rights reserved.
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
use warnings;
use bytes;
-use IO::Uncompress::RawInflate 2.008 ;
-use IO::Compress::Base::Common 2.008 qw(:Status createSelfTiedObject);
-use IO::Uncompress::Adapter::Identity 2.008 ;
-use IO::Compress::Zlib::Extra 2.008 ;
-use IO::Compress::Zip::Constants 2.008 ;
+use IO::Uncompress::RawInflate 2.009 ;
+use IO::Compress::Base::Common 2.009 qw(:Status createSelfTiedObject);
+use IO::Uncompress::Adapter::Identity 2.009 ;
+use IO::Compress::Zlib::Extra 2.009 ;
+use IO::Compress::Zip::Constants 2.009 ;
-use Compress::Raw::Zlib 2.008 qw(crc32) ;
+use Compress::Raw::Zlib 2.009 qw(crc32) ;
BEGIN
{
our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $UnzipError, %headerLookup);
-$VERSION = '2.008';
+$VERSION = '2.009';
$UnzipError = '';
@ISA = qw(Exporter IO::Uncompress::RawInflate);
sub getExtraParams
{
- use IO::Compress::Base::Common 2.008 qw(:Parse);
+ use IO::Compress::Base::Common 2.009 qw(:Parse);
return (
=head1 NAME
-
-
IO::Uncompress::Unzip - Read zip files/buffers
-
-
=head1 SYNOPSIS
use IO::Uncompress::Unzip qw(unzip $UnzipError) ;
eof($z)
close($z)
-
=head1 DESCRIPTION
-
-
This module provides a Perl interface that allows the reading of
zlib files/buffers.
For writing zip files/buffers, see the companion module IO::Compress::Zip.
-
-
-
-
=head1 Functional Interface
A top-level function, C<unzip>, is provided to carry out
unzip $input => $output [,OPTS]
or die "unzip failed: $UnzipError\n";
-
-
The functional interface needs Perl5.005 or better.
-
=head2 unzip $input => $output [, OPTS]
-
C<unzip> expects at least two parameters, C<$input> and C<$output>.
=head3 The C<$input> parameter
The complete array will be walked to ensure that it only
contains valid filenames before any data is uncompressed.
-
-
=item An Input FileGlob string
If C<$input> is a string that is delimited by the characters "<" and ">"
See L<File::GlobMapper|File::GlobMapper> for more details.
-
=back
If the C<$input> parameter is any other type, C<undef> will be returned.
-
-
=head3 The C<$output> parameter
The parameter C<$output> is used to control the destination of the
will be written to it.
The string '-' can be used as an alias for standard output.
-
=item A scalar reference
If C<$output> is a scalar reference, the uncompressed data will be
stored in C<$$output>.
-
-
=item An Array Reference
If C<$output> is an array reference, the uncompressed data will be
If the C<$output> parameter is any other type, C<undef> will be returned.
-
-
=head2 Notes
-
When C<$input> maps to multiple compressed files/buffers and C<$output> is
a single file/buffer, after uncompression C<$output> will contain a
concatenation of all the uncompressed data from each of the input
files/buffers.
-
-
-
-
=head2 Optional Parameters
Unless specified below, the optional parameters for C<unzip>,
This parameter defaults to 0.
-
=item C<< BinModeOut => 0|1 >>
When writing to a file or filehandle, set C<binmode> before writing to the
Defaults to 0.
-
-
-
-
=item C<< Append => 0|1 >>
TODO
=item C<< MultiStream => 0|1 >>
-
If the input file/buffer contains multiple compressed data streams, this
option will uncompress the whole lot as a single data stream.
Defaults to 0.
-
-
-
-
=item C<< TrailingData => $scalar >>
Returns the data, if any, that is present immediately after the compressed
Don't bother using C<trailingData> if the input is a filename.
-
-
If you know the length of the compressed data stream before you start
uncompressing, you can avoid having to use C<trailingData> by setting the
C<InputLength> option.
-
-
=back
-
-
-
=head2 Examples
To read the contents of the file C<file1.txt.zip> and write the
unzip $input => $output
or die "unzip failed: $UnzipError\n";
-
To read from an existing Perl filehandle, C<$input>, and write the
uncompressed data to a buffer, C<$buffer>.
The format of the constructor for IO::Uncompress::Unzip is shown below
-
my $z = new IO::Uncompress::Unzip $input [OPTS]
or die "IO::Uncompress::Unzip failed: $UnzipError\n";
read from it.
The string '-' can be used as an alias for standard input.
-
=item A scalar reference
If C<$input> is a scalar reference, the compressed data will be read from
=head2 Constructor Options
-
The option names defined below are case insensitive and can be optionally
prefixed by a '-'. So all of the following are valid
=item C<< MultiStream => 0|1 >>
-
-
Treats the complete zip file/buffer as a single compressed data
stream. When reading in multi-stream mode each member of the zip
file/buffer will be uncompressed in turn until the end of the file/buffer
This parameter defaults to 0.
-
=item C<< Prime => $string >>
This option will uncompress the contents of C<$string> before processing the
the file pointer will be left pointing to the first byte directly after the
compressed data stream.
-
-
This option defaults to off.
=item C<< Append => 0|1 >>
=item C<< Strict => 0|1 >>
-
-
This option controls whether the extra checks defined below are used when
carrying out the decompression. When Strict is on, the extra tests are
carried out, when Strict is off they are not.
The default for this option is off.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
=back
=head2 Examples
Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
or a negative number on error.
-
=head2 getline
Usage is
determine what constitutes an end of line. Paragraph mode, record mode and
file slurp mode are all supported.
-
=head2 getc
Usage is
$char = $z->ungetc($string)
-
-
=head2 inflateSync
Usage is
TODO
-
=head2 getHeaderInfo
Usage is
or hash references (in array context) that contains information about each
of the header fields in the compressed data stream(s).
-
-
-
=head2 tell
Usage is
$z->eof();
eof($z);
-
-
Returns true if the end of the compressed input stream has been reached.
-
-
=head2 seek
$z->seek($position, $whence);
seek($z, $position, $whence);
-
-
-
Provides a sub-set of the C<seek> functionality, with the restriction
that it is only legal to seek forward in the input file/buffer.
It is a fatal error to attempt to seek backward.
-
-
The C<$whence> parameter takes one the usual values, namely SEEK_SET,
SEEK_CUR or SEEK_END.
$z->input_line_number()
$z->input_line_number(EXPR)
-
-
Returns the current uncompressed line number. If C<EXPR> is present it has
the effect of setting the line number. Note that setting the line number
does not change the current position within the file/buffer being read.
The contents of C<$/> are used to to determine what constitutes a line
terminator.
-
-
=head2 fileno
$z->fileno()
fileno($z)
-If the C<$z> object is associated with a file or a filehandle, this method
-will return the underlying file descriptor.
+If the C<$z> object is associated with a file or a filehandle, C<fileno>
+will return the underlying file descriptor. Once the C<close> method is
+called C<fileno> will return C<undef>.
-If the C<$z> object is is associated with a buffer, this method will
-return undef.
+If the C<$z> object is is associated with a buffer, this method will return
+C<undef>.
=head2 close
$z->close() ;
close $z ;
-
-
Closes the output file/buffer.
-
-
For most versions of Perl this method will be automatically invoked if
the IO::Uncompress::Unzip object is destroyed (either explicitly or by the
variable with the reference to the object going out of scope). The
object was created, and the object is associated with a file, the
underlying file will also be closed.
-
-
-
=head2 nextStream
Usage is
Don't bother using C<trailingData> if the input is a filename.
-
-
If you know the length of the compressed data stream before you start
uncompressing, you can avoid having to use C<trailingData> by setting the
C<InputLength> option in the constructor.
=head1 EXAMPLES
+=head2 Working with Net::FTP
+
+See L<IO::Uncompress::Unzip::FAQ|IO::Uncompress::Unzip::FAQ/"Compressed files and Net::FTP">
+
+=head2 Walking through a zip file
+The code below can be used to traverse a zip file, one compressed data
+stream at a time.
+ use IO::Uncompress::Unzip qw($UnzipError);
+
+ my $zipfile = "somefile.zip";
+ my $u = new IO::Uncompress::Unzip $zipfile
+ or die "Cannot open $filefile: $UnzipError";
+
+ for (my $status = 1; ! $u->eof(); $status = $u->nextStream())
+
+ my $name = $u->getHeaderInfo()->{Name};
+ warn "Processing member $name\n" ;
+
+ my $buff;
+ while (($status = $u->read($buff)) > 0) {
+ # Do something here
+ }
+
+ last unless $status == 0;
+ }
+
+ die "Error processing $zipfile: $!\n"
+ if $status < 0 ;
+
+Each individual compressed data stream is read until the logical
+end-of-file is reached. Then C<nextStream> is called. This will skip to the
+start of the next compressed data stream and clear the end-of-file flag.
+
+It is also worth noting that C<nextStream> can be called at any time -- you
+don't have to wait until you have exhausted a compressed data stream before
+skipping to the next one.
=head1 SEE ALSO
L<Archive::Tar|Archive::Tar>,
L<IO::Zlib|IO::Zlib>
-
For RFC 1950, 1951 and 1952 see
F<http://www.faqs.org/rfcs/rfc1950.html>,
F<http://www.faqs.org/rfcs/rfc1951.html> and
The primary site for gzip is F<http://www.gzip.org>.
-
-
-
=head1 AUTHOR
This module was written by Paul Marquess, F<pmqs@cpan.org>.
-
-
=head1 MODIFICATION HISTORY
See the Changes file.
=head1 COPYRIGHT AND LICENSE
-Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
+Copyright (c) 2005-2008 Paul Marquess. All rights reserved.
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
--- /dev/null
+
+=head1 NAME
+
+IO::Compress::Zlib::FAQ -- Frequently Asked Questions about IO::Compress::Zlib
+
+=head1 DESCRIPTION
+
+Common questions answered.
+
+=head2 Compatibility with Unix compress/uncompress.
+
+This module is not compatible with Unix C<compress>.
+
+If you have the C<uncompress> program available, you can use this to read
+compressed files
+
+ open F, "uncompress -c $filename |";
+ while (<F>)
+ {
+ ...
+
+Alternatively, if you have the C<gunzip> program available, you can use
+this to read compressed files
+
+ open F, "gunzip -c $filename |";
+ while (<F>)
+ {
+ ...
+
+and this to write compress files, if you have the C<compress> program
+available
+
+ open F, "| compress -c $filename ";
+ print F "data";
+ ...
+ close F ;
+
+=head2 Accessing .tar.Z files
+
+See previous FAQ item.
+
+If the C<Archive::Tar> module is installed and either the C<uncompress> or
+C<gunzip> programs are available, you can use one of these workarounds to
+read C<.tar.Z> files.
+
+Firstly with C<uncompress>
+
+ use strict;
+ use warnings;
+ use Archive::Tar;
+
+ open F, "uncompress -c $filename |";
+ my $tar = Archive::Tar->new(*F);
+ ...
+
+and this with C<gunzip>
+
+ use strict;
+ use warnings;
+ use Archive::Tar;
+
+ open F, "gunzip -c $filename |";
+ my $tar = Archive::Tar->new(*F);
+ ...
+
+Similarly, if the C<compress> program is available, you can use this to
+write a C<.tar.Z> file
+
+ use strict;
+ use warnings;
+ use Archive::Tar;
+ use IO::File;
+
+ my $fh = new IO::File "| compress -c >$filename";
+ my $tar = Archive::Tar->new();
+ ...
+ $tar->write($fh);
+ $fh->close ;
+
+=head2 Accessing Zip Files
+
+This module provides support for reading/writing zip files using the
+C<IO::Compress::Zip> and C<IO::Uncompress::Unzip> modules.
+
+The primary focus of the C<IO::Compress::Zip> and C<IO::Uncompress::Unzip>
+modules is to provide an C<IO::File> compatible streaming read/write
+interface to zip files/buffers. They are not fully flegged archivers. If
+you are looking for an archiver check out the C<Archive::Zip> module. You
+can find it on CPAN at
+
+ http://www.cpan.org/modules/by-module/Archive/Archive-Zip-*.tar.gz
+
+=head2 Compressed files and Net::FTP
+
+The C<Net::FTP> module provides two low-level methods called C<stor> and
+C<retr> that both return filehandles. These filehandles can used with the
+C<IO::Compress/Uncompress> modules to compress or uncompress files read
+from or written to an FTP Server on the fly, without having to create a
+temporary file.
+
+Firstly, here is code that uses C<retr> to uncompressed a file as it is
+read from the FTP Server.
+
+ use Net::FTP;
+ use IO::Uncompress::Gunzip qw(:all);
+
+ my $ftp = new Net::FTP ...
+
+ my $retr_fh = $ftp->retr($compressed_filename);
+ gunzip $retr_fh => $outFilename, AutoClose => 1
+ or die "Cannot uncompress '$compressed_file': $GunzipError\n";
+
+and this to compress a file as it is written to the FTP Server
+
+ use Net::FTP;
+ use IO::Compress::Gzip qw(:all);
+
+ my $stor_fh = $ftp->stor($filename);
+ gzip "filename" => $stor_fh, AutoClose => 1
+ or die "Cannot compress '$filename': $GzipError\n";
+
+=head2 How do I recompress using a different compression?
+
+This is easier that you might expect if you realise that all the
+C<IO::Compress::*> objects are derived from C<IO::File> and that all the
+C<IO::Uncompress::*> modules can read from an C<IO::File> filehandle.
+
+So, for example, say you have a file compressed with gzip that you want to
+recompress with bzip2. Here is all that is needed to carry out the
+recompression.
+
+ use IO::Uncompress::Gunzip ':all';
+ use IO::Compress::Bzip2 ':all';
+
+ my $gzipFile = "somefile.gz";
+ my $bzipFile = "somefile.bz2";
+
+ my $gunzip = new IO::Uncompress::Gunzip $gzipFile
+ or die "Cannot gunzip $gzipFile: $GunzipError\n" ;
+
+ bzip2 $gunzip => $bzipFile
+ or die "Cannot bzip2 to $bzipFile: $Bzip2Error\n" ;
+
+Note, there is a limitation of this technique. Some compression file
+formats store extra information along with the compressed data payload. For
+example, gzip can optionally store the original filename and Zip stores a
+lot of information about the original file. If the original compressed file
+contains any of this extra information, it will not be transferred to the
+new compressed file usign the technique above.
+
+=head2 Apache::GZip Revisited
+
+Below is a mod_perl Apache compression module, called C<Apache::GZip>,
+taken from
+F<http://perl.apache.org/docs/tutorials/tips/mod_perl_tricks/mod_perl_tricks.html#On_the_Fly_Compression>
+
+ package Apache::GZip;
+ #File: Apache::GZip.pm
+
+ use strict vars;
+ use Apache::Constants ':common';
+ use Compress::Zlib;
+ use IO::File;
+ use constant GZIP_MAGIC => 0x1f8b;
+ use constant OS_MAGIC => 0x03;
+
+ sub handler {
+ my $r = shift;
+ my ($fh,$gz);
+ my $file = $r->filename;
+ return DECLINED unless $fh=IO::File->new($file);
+ $r->header_out('Content-Encoding'=>'gzip');
+ $r->send_http_header;
+ return OK if $r->header_only;
+
+ tie *STDOUT,'Apache::GZip',$r;
+ print($_) while <$fh>;
+ untie *STDOUT;
+ return OK;
+ }
+
+ sub TIEHANDLE {
+ my($class,$r) = @_;
+ # initialize a deflation stream
+ my $d = deflateInit(-WindowBits=>-MAX_WBITS()) || return undef;
+
+ # gzip header -- don't ask how I found out
+ $r->print(pack("nccVcc",GZIP_MAGIC,Z_DEFLATED,0,time(),0,OS_MAGIC));
+
+ return bless { r => $r,
+ crc => crc32(undef),
+ d => $d,
+ l => 0
+ },$class;
+ }
+
+ sub PRINT {
+ my $self = shift;
+ foreach (@_) {
+ # deflate the data
+ my $data = $self->{d}->deflate($_);
+ $self->{r}->print($data);
+ # keep track of its length and crc
+ $self->{l} += length($_);
+ $self->{crc} = crc32($_,$self->{crc});
+ }
+ }
+
+ sub DESTROY {
+ my $self = shift;
+
+ # flush the output buffers
+ my $data = $self->{d}->flush;
+ $self->{r}->print($data);
+
+ # print the CRC and the total length (uncompressed)
+ $self->{r}->print(pack("LL",@{$self}{qw/crc l/}));
+ }
+
+ 1;
+
+Here's the Apache configuration entry you'll need to make use of it. Once
+set it will result in everything in the /compressed directory will be
+compressed automagically.
+
+ <Location /compressed>
+ SetHandler perl-script
+ PerlHandler Apache::GZip
+ </Location>
+
+Although at first sight there seems to be quite a lot going on in
+C<Apache::GZip>, you could sum up what the code was doing as follows --
+read the contents of the file in C<< $r->filename >>, compress it and write
+the compressed data to standard output. That's all.
+
+This code has to jump through a few hoops to achieve this because
+
+=over
+
+=item 1.
+
+The gzip support in C<Compress::Zlib> version 1.x can only work with a real
+filesystem filehandle. The filehandles used by Apache modules are not
+associated with the filesystem.
+
+=item 2.
+
+That means all the gzip support has to be done by hand - in this case by
+creating a tied filehandle to deal with creating the gzip header and
+trailer.
+
+=back
+
+C<IO::Compress::Gzip> doesn't have that filehandle limitation (this was one
+of the reasons for writing it in the first place). So if
+C<IO::Compress::Gzip> is used instead of C<Compress::Zlib> the whole tied
+filehandle code can be removed. Here is the rewritten code.
+
+ package Apache::GZip;
+
+ use strict vars;
+ use Apache::Constants ':common';
+ use IO::Compress::Gzip;
+ use IO::File;
+
+ sub handler {
+ my $r = shift;
+ my ($fh,$gz);
+ my $file = $r->filename;
+ return DECLINED unless $fh=IO::File->new($file);
+ $r->header_out('Content-Encoding'=>'gzip');
+ $r->send_http_header;
+ return OK if $r->header_only;
+
+ my $gz = new IO::Compress::Gzip '-', Minimal => 1
+ or return DECLINED ;
+
+ print $gz $_ while <$fh>;
+
+ return OK;
+ }
+
+or even more succinctly, like this, using a one-shot gzip
+
+ package Apache::GZip;
+
+ use strict vars;
+ use Apache::Constants ':common';
+ use IO::Compress::Gzip qw(gzip);
+
+ sub handler {
+ my $r = shift;
+ $r->header_out('Content-Encoding'=>'gzip');
+ $r->send_http_header;
+ return OK if $r->header_only;
+
+ gzip $r->filename => '-', Minimal => 1
+ or return DECLINED ;
+
+ return OK;
+ }
+
+ 1;
+
+The use of one-shot C<gzip> above just reads from C<< $r->filename >> and
+writes the compressed data to standard output.
+
+Note the use of the C<Minimal> option in the code above. When using gzip
+for Content-Encoding you should I<always> use this option. In the example
+above it will prevent the filename being included in the gzip header and
+make the size of the gzip data stream a slight bit smaller.
+
+=head2 Using C<InputLength> to uncompress data embedded in a larger file/buffer.
+
+A fairly common use-case is where compressed data is embedded in a larger
+file/buffer and you want to read both.
+
+As an example consider the structure of a zip file. This is a well-defined
+file format that mixes both compressed and uncompressed sections of data in
+a single file.
+
+For the purposes of this discussion you can think of a zip file as sequence
+of compressed data streams, each of which is prefixed by an uncompressed
+local header. The local header contains information about the compressed
+data stream, including the name of the compressed file and, in particular,
+the length of the compressed data stream.
+
+To illustrate how to use C<InputLength> here is a script that walks a zip
+file and prints out how many lines are in each compressed file (if you
+intend write code to walking through a zip file for real see
+L<IO::Uncompress::Unzip/"Walking through a zip file"> )
+
+ use strict;
+ use warnings;
+
+ use IO::File;
+ use IO::Uncompress::RawInflate qw(:all);
+
+ use constant ZIP_LOCAL_HDR_SIG => 0x04034b50;
+ use constant ZIP_LOCAL_HDR_LENGTH => 30;
+
+ my $file = $ARGV[0] ;
+
+ my $fh = new IO::File "<$file"
+ or die "Cannot open '$file': $!\n";
+
+ while (1)
+ {
+ my $sig;
+ my $buffer;
+
+ my $x ;
+ ($x = $fh->read($buffer, ZIP_LOCAL_HDR_LENGTH)) == ZIP_LOCAL_HDR_LENGTH
+ or die "Truncated file: $!\n";
+
+ my $signature = unpack ("V", substr($buffer, 0, 4));
+
+ last unless $signature == ZIP_LOCAL_HDR_SIG;
+
+ # Read Local Header
+ my $gpFlag = unpack ("v", substr($buffer, 6, 2));
+ my $compressedMethod = unpack ("v", substr($buffer, 8, 2));
+ my $compressedLength = unpack ("V", substr($buffer, 18, 4));
+ my $uncompressedLength = unpack ("V", substr($buffer, 22, 4));
+ my $filename_length = unpack ("v", substr($buffer, 26, 2));
+ my $extra_length = unpack ("v", substr($buffer, 28, 2));
+
+ my $filename ;
+ $fh->read($filename, $filename_length) == $filename_length
+ or die "Truncated file\n";
+
+ $fh->read($buffer, $extra_length) == $extra_length
+ or die "Truncated file\n";
+
+ if ($compressedMethod != 8 && $compressedMethod != 0)
+ {
+ warn "Skipping file '$filename' - not deflated $compressedMethod\n";
+ $fh->read($buffer, $compressedLength) == $compressedLength
+ or die "Truncated file\n";
+ next;
+ }
+
+ if ($compressedMethod == 0 && $gpFlag & 8 == 8)
+ {
+ die "Streamed Stored not supported for '$filename'\n";
+ }
+
+ next if $compressedLength == 0;
+
+ # Done reading the Local Header
+
+ my $inf = new IO::Uncompress::RawInflate $fh,
+ Transparent => 1,
+ InputLength => $compressedLength
+ or die "Cannot uncompress $file [$filename]: $RawInflateError\n" ;
+
+ my $line_count = 0;
+
+ while (<$inf>)
+ {
+ ++ $line_count;
+ }
+
+ print "$filename: $line_count\n";
+ }
+
+The majority of the code above is concerned with reading the zip local
+header data. The code that I want to focus on is at the bottom.
+
+ while (1) {
+
+ # read local zip header data
+ # get $filename
+ # get $compressedLength
+
+ my $inf = new IO::Uncompress::RawInflate $fh,
+ Transparent => 1,
+ InputLength => $compressedLength
+ or die "Cannot uncompress $file [$filename]: $RawInflateError\n" ;
+
+ my $line_count = 0;
+
+ while (<$inf>)
+ {
+ ++ $line_count;
+ }
+
+ print "$filename: $line_count\n";
+ }
+
+The call to C<IO::Uncompress::RawInflate> creates a new filehandle C<$inf>
+that can be used to read from the parent filehandle C<$fh>, uncompressing
+it as it goes. The use of the C<InputLength> option will guarantee that
+I<at most> C<$compressedLength> bytes of compressed data will be read from
+the C<$fh> filehandle (The only exception is for an error case like a
+truncated file or a corrupt data stream).
+
+This means that once RawInflate is finished C<$fh> will be left at the
+byte directly after the compressed data stream.
+
+Now consider what the code looks like without C<InputLength>
+
+ while (1) {
+
+ # read local zip header data
+ # get $filename
+ # get $compressedLength
+
+ # read all the compressed data into $data
+ read($fh, $data, $compressedLength);
+
+ my $inf = new IO::Uncompress::RawInflate \$data,
+ Transparent => 1,
+ or die "Cannot uncompress $file [$filename]: $RawInflateError\n" ;
+
+ my $line_count = 0;
+
+ while (<$inf>)
+ {
+ ++ $line_count;
+ }
+
+ print "$filename: $line_count\n";
+ }
+
+The difference here is the addition of the temporary variable C<$data>.
+This is used to store a copy of the compressed data while it is being
+uncompressed.
+
+If you know that C<$compressedLength> isn't that big then using temporary
+storage won't be a problem. But if C<$compressedLength> is very large or
+you are writing an application that other people will use, and so have no
+idea how big C<$compressedLength> will be, it could be an issue.
+
+Using C<InputLength> avoids the use of temporary storage and means the
+application can cope with large compressed data streams.
+
+One final point -- obviously C<InputLength> can only be used whenever you
+know the length of the compressed data beforehand, like here with a zip
+file.
+
+=head1 SEE ALSO
+
+L<Compress::Zlib>, L<IO::Compress::Gzip>, L<IO::Uncompress::Gunzip>, L<IO::Compress::Deflate>, L<IO::Uncompress::Inflate>, L<IO::Compress::RawDeflate>, L<IO::Uncompress::RawInflate>, L<IO::Compress::Bzip2>, L<IO::Uncompress::Bunzip2>, L<IO::Compress::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
+
+L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
+
+L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
+L<Archive::Tar|Archive::Tar>,
+L<IO::Zlib|IO::Zlib>
+
+=head1 AUTHOR
+
+This module was written by Paul Marquess, F<pmqs@cpan.org>.
+
+=head1 MODIFICATION HISTORY
+
+See the Changes file.
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright (c) 2005-2008 Paul Marquess. All rights reserved.
+
+This program is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+
return readFile($filename) eq unpack("u", $uue) ;
}
+sub isRawFormat
+{
+ my $class = shift;
+ my %raw = map { $_ => 1 } qw( RawDeflate );
+
+ return defined $raw{$class};
+}
+
sub uncompressBuffer
{
my $compWith = shift ;
'IO::Compress::Lzop::lzop' => 'IO::Uncompress::UnLzop',
'IO::Compress::Lzf' => 'IO::Uncompress::UnLzf' ,
'IO::Compress::Lzf::lzf' => 'IO::Uncompress::UnLzf',
+ 'IO::Compress::PPMd' => 'IO::Uncompress::UnPPMd' ,
+ 'IO::Compress::PPMd::ppmd' => 'IO::Uncompress::UnPPMd',
'IO::Compress::DummyComp' => 'IO::Uncompress::DummyUncomp',
'IO::Compress::DummyComp::dummycomp' => 'IO::Uncompress::DummyUncomp',
);
'IO::Compress::Lzf::lzf' => \$IO::Compress::Lzf::LzfError,
'IO::Uncompress::UnLzf' => \$IO::Uncompress::UnLzf::UnLzfError,
'IO::Uncompress::UnLzf::unlzf' => \$IO::Uncompress::UnLzf::UnLzfError,
+ 'IO::Compress::PPMd' => \$IO::Compress::PPMd::PPMdError,
+ 'IO::Compress::PPMd::ppmd' => \$IO::Compress::PPMd::PPMdError,
+ 'IO::Uncompress::UnPPMd' => \$IO::Uncompress::UnPPMd::UnPPMdError,
+ 'IO::Uncompress::UnPPMd::unppmd' => \$IO::Uncompress::UnPPMd::UnPPMdError,
'IO::Compress::DummyComp' => \$IO::Compress::DummyComp::DummyCompError,
'IO::Compress::DummyComp::dummycomp'=> \$IO::Compress::DummyComp::DummyCompError,
'IO::Uncompress::UnLzop' => 'IO::Uncompress::UnLzop::unlzop',
'IO::Compress::Lzf' => 'IO::Compress::Lzf::lzf',
'IO::Uncompress::UnLzf' => 'IO::Uncompress::UnLzf::unlzf',
+ 'IO::Compress::PPMd' => 'IO::Compress::PPMd::ppmd',
+ 'IO::Uncompress::UnPPMd' => 'IO::Uncompress::UnPPMd::unppmd',
'IO::Compress::DummyComp' => 'IO::Compress::DummyComp::dummyuncomp',
'IO::Uncompress::DummyUncomp' => 'IO::Uncompress::DummyUncomp::dummyuncomp',
);
'IO::Compress::Lzop' => 'IO::Uncompress::UnLzop',
'IO::Compress::Lzf::lzf' => 'IO::Uncompress::UnLzf::unlzf',
'IO::Compress::Lzf' => 'IO::Uncompress::UnLzf',
+ 'IO::Compress::PPMd::ppmd' => 'IO::Uncompress::UnPPMd::unppmd',
+ 'IO::Compress::PPMd' => 'IO::Uncompress::UnPPMd',
'IO::Compress::DummyComp::dummycomp' => 'IO::Uncompress::DummyUncomp::dummyuncomp',
'IO::Compress::DummyComp' => 'IO::Uncompress::DummyUncomp',
);
'IO::Uncompress::UnLzop::unlzop' => 'IO::Compress::Lzop',
'IO::Uncompress::UnLzp' => 'IO::Compress::Lzf',
'IO::Uncompress::UnLzf::unlzf' => 'IO::Compress::Lzf',
+ 'IO::Uncompress::UnPPMd' => 'IO::Compress::PPMd',
+ 'IO::Uncompress::UnPPMd::unppmd' => 'IO::Compress::PPMd',
'IO::Uncompress::AnyInflate' => 'IO::Compress::Gzip',
'IO::Uncompress::AnyInflate::anyinflate' => 'IO::Compress::Gzip',
'IO::Uncompress::AnyUncompress' => 'IO::Compress::Gzip',
my $Error = getErrorRef($CompressClass);
my $UnError = getErrorRef($UncompressClass);
+ if(1)
{
title "Testing $CompressClass Errors";
like $@, mkEvalErr("^${CompressClass}::write: offset outside string");
eval ' $gz->syswrite("abc", 1, -4)' ;
- like $@, mkEvalErr("^${CompressClass}::write: offset outside string");
+ like $@, mkEvalErr("^${CompressClass}::write: offset outside string"), "write outside string";
}
my $lex = new LexFile my $name ;
- #my $name = "/tmp/try.lzf";
my $hello = <<EOM ;
hello world
ok $x->close, " close" ;
}
- #exit;
is $uncomp, $hello, " expected output" ;
}
ok ! defined $x->fileno() ;
1 while $x->read($uncomp) > 0 ;
- ok $x->close ;
+ ok $x->close, "closed" ;
}
- is $uncomp, $hello ;
- ok $buffer eq $keep ;
+ is $uncomp, $hello, "got expected uncompressed data" ;
+ ok $buffer eq $keep, "compressed input not changed" ;
}
if ($CompressClass ne 'RawDeflate')
my $buffer = '';
{
my $x ;
- ok $x = new $CompressClass(\$buffer) ;
- ok $x->close ;
+ $x = new $CompressClass(\$buffer);
+ ok $x, "new $CompressClass" ;
+ ok $x->close, "close ok" ;
}
read($fh1, $rest, 5000);
is $x->trailingData() . $rest, $trailer ;
#print "# [".$x->trailingData() . "][$rest]\n" ;
- #exit;
}
}
}
-
{
title "write tests - invalid data" ;
projects / p5sagit/p5-mst-13.2.git / commitdiff