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