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