ext/Compress/IO/Zlib/lib/IO/Uncompress/Unzip.pm

   1 package IO::Uncompress::Unzip;
   2
   3 require 5.004 ;
   4
   5 # for RFC1952
   6
   7 use strict ;
   8 use warnings;
   9 use bytes;
  10
  11 use IO::Uncompress::RawInflate ;
  12 use IO::Compress::Base::Common qw(:Status createSelfTiedObject);
  13 use IO::Uncompress::Adapter::Identity;
  14 use IO::Compress::Zlib::Extra;
  15 use IO::Compress::Zip::Constants;
  16
  17 use Compress::Raw::Zlib qw(crc32) ;
  18
  19 BEGIN
  20 {
  21     eval { require IO::Uncompress::Adapter::Bunzip2 ;
  22            import  IO::Uncompress::Adapter::Bunzip2 } ;
  23 }
  24
  25
  26 require Exporter ;
  27
  28 our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $UnzipError);
  29
  30 $VERSION = '2.000_12';
  31 $UnzipError = '';
  32
  33 @ISA    = qw(Exporter IO::Uncompress::RawInflate);
  34 @EXPORT_OK = qw( $UnzipError unzip );
  35 %EXPORT_TAGS = %IO::Uncompress::RawInflate::EXPORT_TAGS ;
  36 push @{ $EXPORT_TAGS{all} }, @EXPORT_OK ;
  37 Exporter::export_ok_tags('all');
  38
  39 sub new
  40 {
  41     my $class = shift ;
  42     my $obj = createSelfTiedObject($class, \$UnzipError);
  43     $obj->_create(undef, 0, @_);
  44 }
  45
  46 sub unzip
  47 {
  48     my $obj = createSelfTiedObject(undef, \$UnzipError);
  49     return $obj->_inf(@_) ;
  50 }
  51
  52 sub getExtraParams
  53 {
  54     use IO::Compress::Base::Common qw(:Parse);
  55
  56
  57     return (
  58 #            # Zip header fields
  59             'Name'      => [1, 1, Parse_any,       undef],
  60
  61 #            'Streaming' => [1, 1, Parse_boolean,   1],
  62         );
  63 }
  64
  65 sub ckParams
  66 {
  67     my $self = shift ;
  68     my $got = shift ;
  69
  70     # unzip always needs crc32
  71     $got->value('CRC32' => 1);
  72
  73     *$self->{UnzipData}{Name} = $got->value('Name');
  74
  75     return 1;
  76 }
  77
  78
  79 sub ckMagic
  80 {
  81     my $self = shift;
  82
  83     my $magic ;
  84     $self->smartReadExact(\$magic, 4);
  85
  86     *$self->{HeaderPending} = $magic ;
  87
  88     return $self->HeaderError("Minimum header size is " .
  89                               4 . " bytes")
  90         if length $magic != 4 ;
  91
  92     return $self->HeaderError("Bad Magic")
  93         if ! _isZipMagic($magic) ;
  94
  95     *$self->{Type} = 'zip';
  96
  97     return $magic ;
  98 }
  99
 100
 101
 102 sub readHeader
 103 {
 104     my $self = shift;
 105     my $magic = shift ;
 106
 107     my $name =  *$self->{UnzipData}{Name} ;
 108     my $hdr = $self->_readZipHeader($magic) ;
 109
 110     while (defined $hdr)
 111     {
 112         if (! defined $name || $hdr->{Name} eq $name)
 113         {
 114             return $hdr ;
 115         }
 116
 117         # skip the data
 118         my $buffer;
 119         if (*$self->{ZipData}{Streaming}) {
 120
 121             while (1) {
 122
 123                 my $b;
 124                 my $status = $self->smartRead(\$b, 1024 * 16);
 125                 return undef
 126                     if $status <= 0 ;
 127
 128                 my $temp_buf;
 129                 my $out;
 130                 $status = *$self->{Uncomp}->uncompr(\$b, \$temp_buf, 0, $out);
 131
 132                 return $self->saveErrorString(undef, *$self->{Uncomp}{Error},
 133                                                      *$self->{Uncomp}{ErrorNo})
 134                     if $self->saveStatus($status) == STATUS_ERROR;
 135
 136                 if ($status == STATUS_ENDSTREAM) {
 137                     *$self->{Uncomp}->reset();
 138                     $self->pushBack($b)  ;
 139                     last;
 140                 }
 141             }
 142
 143             # skip the trailer
 144             $self->smartReadExact(\$buffer, $hdr->{TrailerLength})
 145                 or return $self->saveErrorString(undef, "Truncated file");
 146         }
 147         else {
 148             my $c = $hdr->{CompressedLength};
 149             $self->smartReadExact(\$buffer, $c)
 150                 or return $self->saveErrorString(undef, "Truncated file");
 151             $buffer = '';
 152         }
 153
 154         $self->chkTrailer($buffer) == STATUS_OK
 155             or return $self->saveErrorString(undef, "Truncated file");
 156
 157         $hdr = $self->_readFullZipHeader();
 158
 159         return $self->saveErrorString(undef, "Cannot find '$name'")
 160             if $self->smartEof();
 161     }
 162
 163     return undef;
 164 }
 165
 166 sub chkTrailer
 167 {
 168     my $self = shift;
 169     my $trailer = shift;
 170
 171     my ($sig, $CRC32, $cSize, $uSize) ;
 172     if (*$self->{ZipData}{Streaming}) {
 173         ($sig, $CRC32, $cSize, $uSize) = unpack("V V V V", $trailer) ;
 174         return $self->TrailerError("Data Descriptor signature, got $sig")
 175             if $sig != ZIP_DATA_HDR_SIG;
 176     }
 177     else {
 178         ($CRC32, $cSize, $uSize) =
 179             (*$self->{ZipData}{Crc32},
 180              *$self->{ZipData}{CompressedLen},
 181              *$self->{ZipData}{UnCompressedLen});
 182     }
 183
 184     if (*$self->{Strict}) {
 185         return $self->TrailerError("CRC mismatch")
 186             if $CRC32  != *$self->{ZipData}{CRC32} ;
 187
 188         my $exp_isize = *$self->{Uncomp}->compressedBytes();
 189         return $self->TrailerError("CSIZE mismatch. Got $cSize"
 190                                   . ", expected $exp_isize")
 191             if $cSize != $exp_isize ;
 192
 193         $exp_isize = *$self->{Uncomp}->uncompressedBytes();
 194         return $self->TrailerError("USIZE mismatch. Got $uSize"
 195                                   . ", expected $exp_isize")
 196             if $uSize != $exp_isize ;
 197     }
 198
 199     my $reachedEnd = STATUS_ERROR ;
 200     # check for central directory or end of central directory
 201     while (1)
 202     {
 203         my $magic ;
 204         my $got = $self->smartRead(\$magic, 4);
 205
 206         return $self->saveErrorString(STATUS_ERROR, "Truncated file")
 207             if $got != 4 && *$self->{Strict};
 208
 209         if ($got == 0) {
 210             return STATUS_EOF ;
 211         }
 212         elsif ($got < 0) {
 213             return STATUS_ERROR ;
 214         }
 215         elsif ($got < 4) {
 216             $self->pushBack($magic)  ;
 217             return STATUS_OK ;
 218         }
 219
 220         my $sig = unpack("V", $magic) ;
 221
 222         if ($sig == ZIP_CENTRAL_HDR_SIG)
 223         {
 224             if ($self->skipCentralDirectory($magic) != STATUS_OK ) {
 225                 if (*$self->{Strict}) {
 226                     return STATUS_ERROR ;
 227                 }
 228                 else {
 229                     $self->clearError();
 230                     return STATUS_OK ;
 231                 }
 232             }
 233         }
 234         elsif ($sig == ZIP_END_CENTRAL_HDR_SIG)
 235         {
 236             if ($self->skipEndCentralDirectory($magic) != STATUS_OK) {
 237                 if (*$self->{Strict}) {
 238                     return STATUS_ERROR ;
 239                 }
 240                 else {
 241                     $self->clearError();
 242                     return STATUS_OK ;
 243                 }
 244             }
 245             # $reachedEnd = STATUS_OK ;
 246             return STATUS_OK ;
 247             last;
 248         }
 249         elsif ($sig == ZIP_LOCAL_HDR_SIG)
 250         {
 251             $self->pushBack($magic)  ;
 252             return STATUS_OK ;
 253         }
 254         else
 255         {
 256             # put the data back
 257             $self->pushBack($magic)  ;
 258             last;
 259         }
 260     }
 261
 262     return $reachedEnd ;
 263 }
 264
 265 sub skipCentralDirectory
 266 {
 267     my $self = shift;
 268     my $magic = shift ;
 269
 270     my $buffer;
 271     $self->smartReadExact(\$buffer, 46 - 4)
 272         or return $self->TrailerError("Minimum header size is " .
 273                                      46 . " bytes") ;
 274
 275     my $keep = $magic . $buffer ;
 276     *$self->{HeaderPending} = $keep ;
 277
 278    #my $versionMadeBy      = unpack ("v", substr($buffer, 4-4,  2));
 279    #my $extractVersion     = unpack ("v", substr($buffer, 6-4,  2));
 280    #my $gpFlag             = unpack ("v", substr($buffer, 8-4,  2));
 281    #my $compressedMethod   = unpack ("v", substr($buffer, 10-4, 2));
 282    #my $lastModTime        = unpack ("V", substr($buffer, 12-4, 4));
 283    #my $crc32              = unpack ("V", substr($buffer, 16-4, 4));
 284    #my $compressedLength   = unpack ("V", substr($buffer, 20-4, 4));
 285    #my $uncompressedLength = unpack ("V", substr($buffer, 24-4, 4));
 286     my $filename_length    = unpack ("v", substr($buffer, 28-4, 2));
 287     my $extra_length       = unpack ("v", substr($buffer, 30-4, 2));
 288     my $comment_length     = unpack ("v", substr($buffer, 32-4, 2));
 289    #my $disk_start         = unpack ("v", substr($buffer, 34-4, 2));
 290    #my $int_file_attrib    = unpack ("v", substr($buffer, 36-4, 2));
 291    #my $ext_file_attrib    = unpack ("V", substr($buffer, 38-4, 2));
 292    #my $lcl_hdr_offset     = unpack ("V", substr($buffer, 42-4, 2));
 293
 294
 295     my $filename;
 296     my $extraField;
 297     my $comment ;
 298     if ($filename_length)
 299     {
 300         $self->smartReadExact(\$filename, $filename_length)
 301             or return $self->TruncatedTrailer("filename");
 302         $keep .= $filename ;
 303     }
 304
 305     if ($extra_length)
 306     {
 307         $self->smartReadExact(\$extraField, $extra_length)
 308             or return $self->TruncatedTrailer("extra");
 309         $keep .= $extraField ;
 310     }
 311
 312     if ($comment_length)
 313     {
 314         $self->smartReadExact(\$comment, $comment_length)
 315             or return $self->TruncatedTrailer("comment");
 316         $keep .= $comment ;
 317     }
 318
 319     return STATUS_OK ;
 320 }
 321
 322 sub skipEndCentralDirectory
 323 {
 324     my $self = shift;
 325     my $magic = shift ;
 326
 327     my $buffer;
 328     $self->smartReadExact(\$buffer, 22 - 4)
 329         or return $self->TrailerError("Minimum header size is " .
 330                                      22 . " bytes") ;
 331
 332     my $keep = $magic . $buffer ;
 333     *$self->{HeaderPending} = $keep ;
 334
 335    #my $diskNumber         = unpack ("v", substr($buffer, 4-4,  2));
 336    #my $cntrlDirDiskNo     = unpack ("v", substr($buffer, 6-4,  2));
 337    #my $entriesInThisCD    = unpack ("v", substr($buffer, 8-4,  2));
 338    #my $entriesInCD        = unpack ("v", substr($buffer, 10-4, 2));
 339    #my $sizeOfCD           = unpack ("V", substr($buffer, 12-4, 2));
 340    #my $offsetToCD         = unpack ("V", substr($buffer, 16-4, 2));
 341     my $comment_length     = unpack ("v", substr($buffer, 20-4, 2));
 342
 343
 344     my $comment ;
 345     if ($comment_length)
 346     {
 347         $self->smartReadExact(\$comment, $comment_length)
 348             or return $self->TruncatedTrailer("comment");
 349         $keep .= $comment ;
 350     }
 351
 352     return STATUS_OK ;
 353 }
 354
 355
 356
 357
 358 sub _isZipMagic
 359 {
 360     my $buffer = shift ;
 361     return 0 if length $buffer < 4 ;
 362     my $sig = unpack("V", $buffer) ;
 363     return $sig == ZIP_LOCAL_HDR_SIG ;
 364 }
 365
 366
 367 sub _readFullZipHeader($)
 368 {
 369     my ($self) = @_ ;
 370     my $magic = '' ;
 371
 372     $self->smartReadExact(\$magic, 4);
 373
 374     *$self->{HeaderPending} = $magic ;
 375
 376     return $self->HeaderError("Minimum header size is " .
 377                               30 . " bytes")
 378         if length $magic != 4 ;
 379
 380
 381     return $self->HeaderError("Bad Magic")
 382         if ! _isZipMagic($magic) ;
 383
 384     my $status = $self->_readZipHeader($magic);
 385     delete *$self->{Transparent} if ! defined $status ;
 386     return $status ;
 387 }
 388
 389 sub _readZipHeader($)
 390 {
 391     my ($self, $magic) = @_ ;
 392     my ($HeaderCRC) ;
 393     my ($buffer) = '' ;
 394
 395     $self->smartReadExact(\$buffer, 30 - 4)
 396         or return $self->HeaderError("Minimum header size is " .
 397                                      30 . " bytes") ;
 398
 399     my $keep = $magic . $buffer ;
 400     *$self->{HeaderPending} = $keep ;
 401
 402     my $extractVersion     = unpack ("v", substr($buffer, 4-4,  2));
 403     my $gpFlag             = unpack ("v", substr($buffer, 6-4,  2));
 404     my $compressedMethod   = unpack ("v", substr($buffer, 8-4,  2));
 405     my $lastModTime        = unpack ("V", substr($buffer, 10-4, 4));
 406     my $crc32              = unpack ("V", substr($buffer, 14-4, 4));
 407     my $compressedLength   = unpack ("V", substr($buffer, 18-4, 4));
 408     my $uncompressedLength = unpack ("V", substr($buffer, 22-4, 4));
 409     my $filename_length    = unpack ("v", substr($buffer, 26-4, 2));
 410     my $extra_length       = unpack ("v", substr($buffer, 28-4, 2));
 411
 412     my $filename;
 413     my $extraField;
 414     my @EXTRA = ();
 415     my $streamingMode = ($gpFlag & ZIP_GP_FLAG_STREAMING_MASK) ? 1 : 0 ;
 416
 417     return $self->HeaderError("Streamed Stored content not supported")
 418         if $streamingMode && $compressedMethod == 0 ;
 419
 420     *$self->{ZipData}{Streaming} = $streamingMode;
 421
 422     if (! $streamingMode) {
 423         *$self->{ZipData}{Streaming} = 0;
 424         *$self->{ZipData}{Crc32} = $crc32;
 425         *$self->{ZipData}{CompressedLen} = $compressedLength;
 426         *$self->{ZipData}{UnCompressedLen} = $uncompressedLength;
 427         *$self->{CompressedInputLengthRemaining} =
 428             *$self->{CompressedInputLength} = $compressedLength;
 429     }
 430
 431
 432     if ($filename_length)
 433     {
 434         $self->smartReadExact(\$filename, $filename_length)
 435             or return $self->TruncatedHeader("Filename");
 436         $keep .= $filename ;
 437     }
 438
 439     if ($extra_length)
 440     {
 441         $self->smartReadExact(\$extraField, $extra_length)
 442             or return $self->TruncatedHeader("Extra Field");
 443
 444         my $bad = IO::Compress::Zlib::Extra::parseRawExtra($extraField,
 445                                                 \@EXTRA, 1, 0);
 446         return $self->HeaderError($bad)
 447             if defined $bad;
 448
 449         $keep .= $extraField ;
 450     }
 451
 452     *$self->{ZipData}{Method} = $compressedMethod;
 453     if ($compressedMethod == ZIP_CM_DEFLATE)
 454     {
 455         *$self->{Type} = 'zip-deflate';
 456     }
 457     elsif ($compressedMethod == ZIP_CM_BZIP2)
 458     {
 459     #if (! defined $IO::Uncompress::Adapter::Bunzip2::VERSION)
 460
 461         *$self->{Type} = 'zip-bzip2';
 462
 463         my $obj = IO::Uncompress::Adapter::Bunzip2::mkUncompObject(
 464                                                               );
 465
 466         *$self->{Uncomp} = $obj;
 467         *$self->{ZipData}{CRC32} = crc32(undef);
 468
 469     }
 470     elsif ($compressedMethod == ZIP_CM_STORE)
 471     {
 472         # TODO -- add support for reading uncompressed
 473
 474         *$self->{Type} = 'zip-stored';
 475
 476         my $obj = IO::Uncompress::Adapter::Identity::mkUncompObject(# $got->value('CRC32'),
 477                                                              # $got->value('ADLER32'),
 478                                                               );
 479
 480         *$self->{Uncomp} = $obj;
 481
 482     }
 483     else
 484     {
 485         return $self->HeaderError("Unsupported Compression format $compressedMethod");
 486     }
 487
 488     return {
 489         'Type'               => 'zip',
 490         'FingerprintLength'  => 4,
 491         #'HeaderLength'       => $compressedMethod == 8 ? length $keep : 0,
 492         'HeaderLength'       => length $keep,
 493         'TrailerLength'      => $streamingMode ? 16  : 0,
 494         'Header'             => $keep,
 495         'CompressedLength'   => $compressedLength ,
 496         'UncompressedLength' => $uncompressedLength ,
 497         'CRC32'              => $crc32 ,
 498         'Name'               => $filename,
 499         'Time'               => _dosToUnixTime($lastModTime),
 500         'Stream'             => $streamingMode,
 501
 502         'MethodID'           => $compressedMethod,
 503         'MethodName'         => $compressedMethod == ZIP_CM_DEFLATE
 504                                  ? "Deflated"
 505                                  : $compressedMethod == ZIP_CM_BZIP2
 506                                      ? "Bzip2"
 507                                      : $compressedMethod == ZIP_CM_STORE
 508                                          ? "Stored"
 509                                          : "Unknown" ,
 510
 511 #        'TextFlag'      => $flag & GZIP_FLG_FTEXT ? 1 : 0,
 512 #        'HeaderCRCFlag' => $flag & GZIP_FLG_FHCRC ? 1 : 0,
 513 #        'NameFlag'      => $flag & GZIP_FLG_FNAME ? 1 : 0,
 514 #        'CommentFlag'   => $flag & GZIP_FLG_FCOMMENT ? 1 : 0,
 515 #        'ExtraFlag'     => $flag & GZIP_FLG_FEXTRA ? 1 : 0,
 516 #        'Comment'       => $comment,
 517 #        'OsID'          => $os,
 518 #        'OsName'        => defined $GZIP_OS_Names{$os}
 519 #                                 ? $GZIP_OS_Names{$os} : "Unknown",
 520 #        'HeaderCRC'     => $HeaderCRC,
 521 #        'Flags'         => $flag,
 522 #        'ExtraFlags'    => $xfl,
 523         'ExtraFieldRaw' => $extraField,
 524         'ExtraField'    => [ @EXTRA ],
 525
 526
 527       }
 528 }
 529
 530 sub filterUncompressed
 531 {
 532     my $self = shift ;
 533
 534     if (*$self->{ZipData}{Method} == 12) {
 535         *$self->{ZipData}{CRC32} = crc32(${$_[0]}, *$self->{ZipData}{CRC32});
 536     }
 537     else {
 538         *$self->{ZipData}{CRC32} = *$self->{Uncomp}->crc32() ;
 539     }
 540 }
 541
 542
 543 # from Archive::Zip
 544 sub _dosToUnixTime
 545 {
 546     #use Time::Local 'timelocal_nocheck';
 547     use Time::Local 'timelocal';
 548
 549         my $dt = shift;
 550
 551         my $year = ( ( $dt >> 25 ) & 0x7f ) + 80;
 552         my $mon  = ( ( $dt >> 21 ) & 0x0f ) - 1;
 553         my $mday = ( ( $dt >> 16 ) & 0x1f );
 554
 555         my $hour = ( ( $dt >> 11 ) & 0x1f );
 556         my $min  = ( ( $dt >> 5 ) & 0x3f );
 557         my $sec  = ( ( $dt << 1 ) & 0x3e );
 558
 559         # catch errors
 560         my $time_t =
 561           eval { timelocal( $sec, $min, $hour, $mday, $mon, $year ); };
 562         return 0
 563         if $@;
 564         return $time_t;
 565 }
 566
 567
 568 1;
 569
 570 __END__
 571
 572
 573 =head1 NAME
 574
 575
 576
 577 IO::Uncompress::Unzip - Read zip files/buffers
 578
 579
 580
 581 =head1 SYNOPSIS
 582
 583     use IO::Uncompress::Unzip qw(unzip $UnzipError) ;
 584
 585     my $status = unzip $input => $output [,OPTS]
 586         or die "unzip failed: $UnzipError\n";
 587
 588     my $z = new IO::Uncompress::Unzip $input [OPTS]
 589         or die "unzip failed: $UnzipError\n";
 590
 591     $status = $z->read($buffer)
 592     $status = $z->read($buffer, $length)
 593     $status = $z->read($buffer, $length, $offset)
 594     $line = $z->getline()
 595     $char = $z->getc()
 596     $char = $z->ungetc()
 597     $char = $z->opened()
 598
 599     $status = $z->inflateSync()
 600
 601     $z->trailingData()
 602     $data = $z->getHeaderInfo()
 603     $z->tell()
 604     $z->seek($position, $whence)
 605     $z->binmode()
 606     $z->fileno()
 607     $z->eof()
 608     $z->close()
 609
 610     $UnzipError ;
 611
 612     # IO::File mode
 613
 614     <$z>
 615     read($z, $buffer);
 616     read($z, $buffer, $length);
 617     read($z, $buffer, $length, $offset);
 618     tell($z)
 619     seek($z, $position, $whence)
 620     binmode($z)
 621     fileno($z)
 622     eof($z)
 623     close($z)
 624
 625
 626 =head1 DESCRIPTION
 627
 628
 629
 630 B<WARNING -- This is a Beta release>.
 631
 632 =over 5
 633
 634 =item * DO NOT use in production code.
 635
 636 =item * The documentation is incomplete in places.
 637
 638 =item * Parts of the interface defined here are tentative.
 639
 640 =item * Please report any problems you find.
 641
 642 =back
 643
 644
 645
 646
 647
 648 This module provides a Perl interface that allows the reading of
 649 zlib files/buffers.
 650
 651 For writing zip files/buffers, see the companion module IO::Compress::Zip.
 652
 653
 654
 655
 656
 657
 658 =head1 Functional Interface
 659
 660 A top-level function, C<unzip>, is provided to carry out
 661 "one-shot" uncompression between buffers and/or files. For finer
 662 control over the uncompression process, see the L</"OO Interface">
 663 section.
 664
 665     use IO::Uncompress::Unzip qw(unzip $UnzipError) ;
 666
 667     unzip $input => $output [,OPTS]
 668         or die "unzip failed: $UnzipError\n";
 669
 670
 671
 672 The functional interface needs Perl5.005 or better.
 673
 674
 675 =head2 unzip $input => $output [, OPTS]
 676
 677
 678 C<unzip> expects at least two parameters, C<$input> and C<$output>.
 679
 680 =head3 The C<$input> parameter
 681
 682 The parameter, C<$input>, is used to define the source of
 683 the compressed data.
 684
 685 It can take one of the following forms:
 686
 687 =over 5
 688
 689 =item A filename
 690
 691 If the C<$input> parameter is a simple scalar, it is assumed to be a
 692 filename. This file will be opened for reading and the input data
 693 will be read from it.
 694
 695 =item A filehandle
 696
 697 If the C<$input> parameter is a filehandle, the input data will be
 698 read from it.
 699 The string '-' can be used as an alias for standard input.
 700
 701 =item A scalar reference
 702
 703 If C<$input> is a scalar reference, the input data will be read
 704 from C<$$input>.
 705
 706 =item An array reference
 707
 708 If C<$input> is an array reference, each element in the array must be a
 709 filename.
 710
 711 The input data will be read from each file in turn.
 712
 713 The complete array will be walked to ensure that it only
 714 contains valid filenames before any data is uncompressed.
 715
 716
 717
 718 =item An Input FileGlob string
 719
 720 If C<$input> is a string that is delimited by the characters "<" and ">"
 721 C<unzip> will assume that it is an I<input fileglob string>. The
 722 input is the list of files that match the fileglob.
 723
 724 If the fileglob does not match any files ...
 725
 726 See L<File::GlobMapper|File::GlobMapper> for more details.
 727
 728
 729 =back
 730
 731 If the C<$input> parameter is any other type, C<undef> will be returned.
 732
 733
 734
 735 =head3 The C<$output> parameter
 736
 737 The parameter C<$output> is used to control the destination of the
 738 uncompressed data. This parameter can take one of these forms.
 739
 740 =over 5
 741
 742 =item A filename
 743
 744 If the C<$output> parameter is a simple scalar, it is assumed to be a
 745 filename.  This file will be opened for writing and the uncompressed
 746 data will be written to it.
 747
 748 =item A filehandle
 749
 750 If the C<$output> parameter is a filehandle, the uncompressed data
 751 will be written to it.
 752 The string '-' can be used as an alias for standard output.
 753
 754
 755 =item A scalar reference
 756
 757 If C<$output> is a scalar reference, the uncompressed data will be
 758 stored in C<$$output>.
 759
 760
 761
 762 =item An Array Reference
 763
 764 If C<$output> is an array reference, the uncompressed data will be
 765 pushed onto the array.
 766
 767 =item An Output FileGlob
 768
 769 If C<$output> is a string that is delimited by the characters "<" and ">"
 770 C<unzip> will assume that it is an I<output fileglob string>. The
 771 output is the list of files that match the fileglob.
 772
 773 When C<$output> is an fileglob string, C<$input> must also be a fileglob
 774 string. Anything else is an error.
 775
 776 =back
 777
 778 If the C<$output> parameter is any other type, C<undef> will be returned.
 779
 780
 781
 782 =head2 Notes
 783
 784
 785 When C<$input> maps to multiple compressed files/buffers and C<$output> is
 786 a single file/buffer, after uncompression C<$output> will contain a
 787 concatenation of all the uncompressed data from each of the input
 788 files/buffers.
 789
 790
 791
 792
 793
 794 =head2 Optional Parameters
 795
 796 Unless specified below, the optional parameters for C<unzip>,
 797 C<OPTS>, are the same as those used with the OO interface defined in the
 798 L</"Constructor Options"> section below.
 799
 800 =over 5
 801
 802 =item AutoClose =E<gt> 0|1
 803
 804 This option applies to any input or output data streams to
 805 C<unzip> that are filehandles.
 806
 807 If C<AutoClose> is specified, and the value is true, it will result in all
 808 input and/or output filehandles being closed once C<unzip> has
 809 completed.
 810
 811 This parameter defaults to 0.
 812
 813
 814
 815 =item BinModeOut =E<gt> 0|1
 816
 817 When writing to a file or filehandle, set C<binmode> before writing to the
 818 file.
 819
 820 Defaults to 0.
 821
 822
 823
 824
 825
 826 =item -Append =E<gt> 0|1
 827
 828 TODO
 829
 830 =item -MultiStream =E<gt> 0|1
 831
 832 Creates a new stream after each file.
 833
 834 Defaults to 1.
 835
 836
 837
 838 =back
 839
 840
 841
 842
 843 =head2 Examples
 844
 845 To read the contents of the file C<file1.txt.zip> and write the
 846 compressed data to the file C<file1.txt>.
 847
 848     use strict ;
 849     use warnings ;
 850     use IO::Uncompress::Unzip qw(unzip $UnzipError) ;
 851
 852     my $input = "file1.txt.zip";
 853     my $output = "file1.txt";
 854     unzip $input => $output
 855         or die "unzip failed: $UnzipError\n";
 856
 857
 858 To read from an existing Perl filehandle, C<$input>, and write the
 859 uncompressed data to a buffer, C<$buffer>.
 860
 861     use strict ;
 862     use warnings ;
 863     use IO::Uncompress::Unzip qw(unzip $UnzipError) ;
 864     use IO::File ;
 865
 866     my $input = new IO::File "<file1.txt.zip"
 867         or die "Cannot open 'file1.txt.zip': $!\n" ;
 868     my $buffer ;
 869     unzip $input => \$buffer
 870         or die "unzip failed: $UnzipError\n";
 871
 872 To uncompress all files in the directory "/my/home" that match "*.txt.zip" and store the compressed data in the same directory
 873
 874     use strict ;
 875     use warnings ;
 876     use IO::Uncompress::Unzip qw(unzip $UnzipError) ;
 877
 878     unzip '</my/home/*.txt.zip>' => '</my/home/#1.txt>'
 879         or die "unzip failed: $UnzipError\n";
 880
 881 and if you want to compress each file one at a time, this will do the trick
 882
 883     use strict ;
 884     use warnings ;
 885     use IO::Uncompress::Unzip qw(unzip $UnzipError) ;
 886
 887     for my $input ( glob "/my/home/*.txt.zip" )
 888     {
 889         my $output = $input;
 890         $output =~ s/.zip// ;
 891         unzip $input => $output
 892             or die "Error compressing '$input': $UnzipError\n";
 893     }
 894
 895 =head1 OO Interface
 896
 897 =head2 Constructor
 898
 899 The format of the constructor for IO::Uncompress::Unzip is shown below
 900
 901
 902     my $z = new IO::Uncompress::Unzip $input [OPTS]
 903         or die "IO::Uncompress::Unzip failed: $UnzipError\n";
 904
 905 Returns an C<IO::Uncompress::Unzip> object on success and undef on failure.
 906 The variable C<$UnzipError> will contain an error message on failure.
 907
 908 If you are running Perl 5.005 or better the object, C<$z>, returned from
 909 IO::Uncompress::Unzip can be used exactly like an L<IO::File|IO::File> filehandle.
 910 This means that all normal input file operations can be carried out with
 911 C<$z>.  For example, to read a line from a compressed file/buffer you can
 912 use either of these forms
 913
 914     $line = $z->getline();
 915     $line = <$z>;
 916
 917 The mandatory parameter C<$input> is used to determine the source of the
 918 compressed data. This parameter can take one of three forms.
 919
 920 =over 5
 921
 922 =item A filename
 923
 924 If the C<$input> parameter is a scalar, it is assumed to be a filename. This
 925 file will be opened for reading and the compressed data will be read from it.
 926
 927 =item A filehandle
 928
 929 If the C<$input> parameter is a filehandle, the compressed data will be
 930 read from it.
 931 The string '-' can be used as an alias for standard input.
 932
 933
 934 =item A scalar reference
 935
 936 If C<$input> is a scalar reference, the compressed data will be read from
 937 C<$$output>.
 938
 939 =back
 940
 941 =head2 Constructor Options
 942
 943
 944 The option names defined below are case insensitive and can be optionally
 945 prefixed by a '-'.  So all of the following are valid
 946
 947     -AutoClose
 948     -autoclose
 949     AUTOCLOSE
 950     autoclose
 951
 952 OPTS is a combination of the following options:
 953
 954 =over 5
 955
 956 =item -AutoClose =E<gt> 0|1
 957
 958 This option is only valid when the C<$input> parameter is a filehandle. If
 959 specified, and the value is true, it will result in the file being closed once
 960 either the C<close> method is called or the IO::Uncompress::Unzip object is
 961 destroyed.
 962
 963 This parameter defaults to 0.
 964
 965 =item -MultiStream =E<gt> 0|1
 966
 967
 968
 969 Allows multiple concatenated compressed streams to be treated as a single
 970 compressed stream. Decompression will stop once either the end of the
 971 file/buffer is reached, an error is encountered (premature eof, corrupt
 972 compressed data) or the end of a stream is not immediately followed by the
 973 start of another stream.
 974
 975 This parameter defaults to 0.
 976
 977
 978
 979 =item -Prime =E<gt> $string
 980
 981 This option will uncompress the contents of C<$string> before processing the
 982 input file/buffer.
 983
 984 This option can be useful when the compressed data is embedded in another
 985 file/data structure and it is not possible to work out where the compressed
 986 data begins without having to read the first few bytes. If this is the
 987 case, the uncompression can be I<primed> with these bytes using this
 988 option.
 989
 990 =item -Transparent =E<gt> 0|1
 991
 992 If this option is set and the input file or buffer is not compressed data,
 993 the module will allow reading of it anyway.
 994
 995 This option defaults to 1.
 996
 997 =item -BlockSize =E<gt> $num
 998
 999 When reading the compressed input data, IO::Uncompress::Unzip will read it in
1000 blocks of C<$num> bytes.
1001
1002 This option defaults to 4096.
1003
1004 =item -InputLength =E<gt> $size
1005
1006 When present this option will limit the number of compressed bytes read
1007 from the input file/buffer to C<$size>. This option can be used in the
1008 situation where there is useful data directly after the compressed data
1009 stream and you know beforehand the exact length of the compressed data
1010 stream.
1011
1012 This option is mostly used when reading from a filehandle, in which case
1013 the file pointer will be left pointing to the first byte directly after the
1014 compressed data stream.
1015
1016
1017
1018 This option defaults to off.
1019
1020 =item -Append =E<gt> 0|1
1021
1022 This option controls what the C<read> method does with uncompressed data.
1023
1024 If set to 1, all uncompressed data will be appended to the output parameter
1025 of the C<read> method.
1026
1027 If set to 0, the contents of the output parameter of the C<read> method
1028 will be overwritten by the uncompressed data.
1029
1030 Defaults to 0.
1031
1032 =item -Strict =E<gt> 0|1
1033
1034
1035
1036 This option controls whether the extra checks defined below are used when
1037 carrying out the decompression. When Strict is on, the extra tests are
1038 carried out, when Strict is off they are not.
1039
1040 The default for this option is off.
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055 =back
1056
1057 =head2 Examples
1058
1059 TODO
1060
1061 =head1 Methods
1062
1063 =head2 read
1064
1065 Usage is
1066
1067     $status = $z->read($buffer)
1068
1069 Reads a block of compressed data (the size the the compressed block is
1070 determined by the C<Buffer> option in the constructor), uncompresses it and
1071 writes any uncompressed data into C<$buffer>. If the C<Append> parameter is
1072 set in the constructor, the uncompressed data will be appended to the
1073 C<$buffer> parameter. Otherwise C<$buffer> will be overwritten.
1074
1075 Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
1076 or a negative number on error.
1077
1078 =head2 read
1079
1080 Usage is
1081
1082     $status = $z->read($buffer, $length)
1083     $status = $z->read($buffer, $length, $offset)
1084
1085     $status = read($z, $buffer, $length)
1086     $status = read($z, $buffer, $length, $offset)
1087
1088 Attempt to read C<$length> bytes of uncompressed data into C<$buffer>.
1089
1090 The main difference between this form of the C<read> method and the
1091 previous one, is that this one will attempt to return I<exactly> C<$length>
1092 bytes. The only circumstances that this function will not is if end-of-file
1093 or an IO error is encountered.
1094
1095 Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
1096 or a negative number on error.
1097
1098
1099 =head2 getline
1100
1101 Usage is
1102
1103     $line = $z->getline()
1104     $line = <$z>
1105
1106 Reads a single line.
1107
1108 This method fully supports the use of of the variable C<$/>
1109 (or C<$INPUT_RECORD_SEPARATOR> or C<$RS> when C<English> is in use) to
1110 determine what constitutes an end of line. Both paragraph mode and file
1111 slurp mode are supported.
1112
1113
1114 =head2 getc
1115
1116 Usage is
1117
1118     $char = $z->getc()
1119
1120 Read a single character.
1121
1122 =head2 ungetc
1123
1124 Usage is
1125
1126     $char = $z->ungetc($string)
1127
1128
1129
1130 =head2 inflateSync
1131
1132 Usage is
1133
1134     $status = $z->inflateSync()
1135
1136 TODO
1137
1138
1139 =head2 getHeaderInfo
1140
1141 Usage is
1142
1143     $hdr  = $z->getHeaderInfo();
1144     @hdrs = $z->getHeaderInfo();
1145
1146 This method returns either a hash reference (in scalar context) or a list
1147 or hash references (in array context) that contains information about each
1148 of the header fields in the compressed data stream(s).
1149
1150
1151
1152
1153 =head2 tell
1154
1155 Usage is
1156
1157     $z->tell()
1158     tell $z
1159
1160 Returns the uncompressed file offset.
1161
1162 =head2 eof
1163
1164 Usage is
1165
1166     $z->eof();
1167     eof($z);
1168
1169
1170
1171 Returns true if the end of the compressed input stream has been reached.
1172
1173
1174
1175 =head2 seek
1176
1177     $z->seek($position, $whence);
1178     seek($z, $position, $whence);
1179
1180
1181
1182
1183 Provides a sub-set of the C<seek> functionality, with the restriction
1184 that it is only legal to seek forward in the input file/buffer.
1185 It is a fatal error to attempt to seek backward.
1186
1187
1188
1189 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
1190 SEEK_CUR or SEEK_END.
1191
1192 Returns 1 on success, 0 on failure.
1193
1194 =head2 binmode
1195
1196 Usage is
1197
1198     $z->binmode
1199     binmode $z ;
1200
1201 This is a noop provided for completeness.
1202
1203 =head2 opened
1204
1205     $z->opened()
1206
1207 Returns true if the object currently refers to a opened file/buffer.
1208
1209 =head2 autoflush
1210
1211     my $prev = $z->autoflush()
1212     my $prev = $z->autoflush(EXPR)
1213
1214 If the C<$z> object is associated with a file or a filehandle, this method
1215 returns the current autoflush setting for the underlying filehandle. If
1216 C<EXPR> is present, and is non-zero, it will enable flushing after every
1217 write/print operation.
1218
1219 If C<$z> is associated with a buffer, this method has no effect and always
1220 returns C<undef>.
1221
1222 B<Note> that the special variable C<$|> B<cannot> be used to set or
1223 retrieve the autoflush setting.
1224
1225 =head2 input_line_number
1226
1227     $z->input_line_number()
1228     $z->input_line_number(EXPR)
1229
1230
1231
1232 Returns the current uncompressed line number. If C<EXPR> is present it has
1233 the effect of setting the line number. Note that setting the line number
1234 does not change the current position within the file/buffer being read.
1235
1236 The contents of C<$/> are used to to determine what constitutes a line
1237 terminator.
1238
1239
1240
1241 =head2 fileno
1242
1243     $z->fileno()
1244     fileno($z)
1245
1246 If the C<$z> object is associated with a file or a filehandle, this method
1247 will return the underlying file descriptor.
1248
1249 If the C<$z> object is is associated with a buffer, this method will
1250 return undef.
1251
1252 =head2 close
1253
1254     $z->close() ;
1255     close $z ;
1256
1257
1258
1259 Closes the output file/buffer.
1260
1261
1262
1263 For most versions of Perl this method will be automatically invoked if
1264 the IO::Uncompress::Unzip object is destroyed (either explicitly or by the
1265 variable with the reference to the object going out of scope). The
1266 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
1267 these cases, the C<close> method will be called automatically, but
1268 not until global destruction of all live objects when the program is
1269 terminating.
1270
1271 Therefore, if you want your scripts to be able to run on all versions
1272 of Perl, you should call C<close> explicitly and not rely on automatic
1273 closing.
1274
1275 Returns true on success, otherwise 0.
1276
1277 If the C<AutoClose> option has been enabled when the IO::Uncompress::Unzip
1278 object was created, and the object is associated with a file, the
1279 underlying file will also be closed.
1280
1281
1282
1283
1284 =head1 Importing
1285
1286 No symbolic constants are required by this IO::Uncompress::Unzip at present.
1287
1288 =over 5
1289
1290 =item :all
1291
1292 Imports C<unzip> and C<$UnzipError>.
1293 Same as doing this
1294
1295     use IO::Uncompress::Unzip qw(unzip $UnzipError) ;
1296
1297 =back
1298
1299 =head1 EXAMPLES
1300
1301
1302
1303
1304 =head1 SEE ALSO
1305
1306 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::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
1307
1308 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1309
1310 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1311 L<Archive::Tar|Archive::Tar>,
1312 L<IO::Zlib|IO::Zlib>
1313
1314
1315 For RFC 1950, 1951 and 1952 see
1316 F<http://www.faqs.org/rfcs/rfc1950.html>,
1317 F<http://www.faqs.org/rfcs/rfc1951.html> and
1318 F<http://www.faqs.org/rfcs/rfc1952.html>
1319
1320 The I<zlib> compression library was written by Jean-loup Gailly
1321 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1322
1323 The primary site for the I<zlib> compression library is
1324 F<http://www.zlib.org>.
1325
1326 The primary site for gzip is F<http://www.gzip.org>.
1327
1328
1329
1330
1331 =head1 AUTHOR
1332
1333 This module was written by Paul Marquess, F<pmqs@cpan.org>.
1334
1335
1336
1337 =head1 MODIFICATION HISTORY
1338
1339 See the Changes file.
1340
1341 =head1 COPYRIGHT AND LICENSE
1342
1343 Copyright (c) 2005-2006 Paul Marquess. All rights reserved.
1344
1345 This program is free software; you can redistribute it and/or
1346 modify it under the same terms as Perl itself.
1347