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

   1 package IO::Uncompress::Inflate ;
   2 # for RFC1950
   3
   4 use strict ;
   5 use warnings;
   6 use IO::Uncompress::Gunzip ;
   7
   8
   9 require Exporter ;
  10 our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $InflateError);
  11
  12 $VERSION = '2.000_05';
  13 $InflateError = '';
  14
  15 @ISA    = qw( Exporter IO::BaseInflate );
  16 @EXPORT_OK = qw( $InflateError inflate ) ;
  17 %EXPORT_TAGS = %IO::BaseInflate::EXPORT_TAGS ;
  18 push @{ $EXPORT_TAGS{all} }, @EXPORT_OK ;
  19 Exporter::export_ok_tags('all');
  20
  21
  22 sub new
  23 {
  24     my $pkg = shift ;
  25     return IO::BaseInflate::new($pkg, 'rfc1950', undef, \$InflateError, 0, @_);
  26 }
  27
  28 sub inflate
  29 {
  30     return IO::BaseInflate::_inf(__PACKAGE__, 'rfc1950', \$InflateError, @_);
  31 }
  32
  33 1 ;
  34
  35 __END__
  36
  37
  38 =head1 NAME
  39
  40 IO::Uncompress::Inflate - Perl interface to read RFC 1950 files/buffers
  41
  42 =head1 SYNOPSIS
  43
  44     use IO::Uncompress::Inflate qw(inflate $InflateError) ;
  45
  46     my $status = inflate $input => $output [,OPTS]
  47         or die "inflate failed: $InflateError\n";
  48
  49     my $z = new IO::Uncompress::Inflate $input [OPTS]
  50         or die "inflate failed: $InflateError\n";
  51
  52     $status = $z->read($buffer)
  53     $status = $z->read($buffer, $length)
  54     $status = $z->read($buffer, $length, $offset)
  55     $line = $z->getline()
  56     $char = $z->getc()
  57     $char = $z->ungetc()
  58     $status = $z->inflateSync()
  59     $z->trailingData()
  60     $data = $z->getHeaderInfo()
  61     $z->tell()
  62     $z->seek($position, $whence)
  63     $z->binmode()
  64     $z->fileno()
  65     $z->eof()
  66     $z->close()
  67
  68     $InflateError ;
  69
  70     # IO::File mode
  71
  72     <$z>
  73     read($z, $buffer);
  74     read($z, $buffer, $length);
  75     read($z, $buffer, $length, $offset);
  76     tell($z)
  77     seek($z, $position, $whence)
  78     binmode($z)
  79     fileno($z)
  80     eof($z)
  81     close($z)
  82
  83
  84 =head1 DESCRIPTION
  85
  86
  87
  88 B<WARNING -- This is a Beta release>.
  89
  90 =over 5
  91
  92 =item * DO NOT use in production code.
  93
  94 =item * The documentation is incomplete in places.
  95
  96 =item * Parts of the interface defined here are tentative.
  97
  98 =item * Please report any problems you find.
  99
 100 =back
 101
 102
 103
 104
 105
 106 This module provides a Perl interface that allows the reading of
 107 files/buffers that conform to RFC 1950.
 108
 109 For writing RFC 1950 files/buffers, see the companion module
 110 IO::Compress::Deflate.
 111
 112
 113
 114 =head1 Functional Interface
 115
 116 A top-level function, C<inflate>, is provided to carry out "one-shot"
 117 uncompression between buffers and/or files. For finer control over the uncompression process, see the L</"OO Interface"> section.
 118
 119     use IO::Uncompress::Inflate qw(inflate $InflateError) ;
 120
 121     inflate $input => $output [,OPTS]
 122         or die "inflate failed: $InflateError\n";
 123
 124     inflate \%hash [,OPTS]
 125         or die "inflate failed: $InflateError\n";
 126
 127 The functional interface needs Perl5.005 or better.
 128
 129
 130 =head2 inflate $input => $output [, OPTS]
 131
 132 If the first parameter is not a hash reference C<inflate> expects
 133 at least two parameters, C<$input> and C<$output>.
 134
 135 =head3 The C<$input> parameter
 136
 137 The parameter, C<$input>, is used to define the source of
 138 the compressed data.
 139
 140 It can take one of the following forms:
 141
 142 =over 5
 143
 144 =item A filename
 145
 146 If the C<$input> parameter is a simple scalar, it is assumed to be a
 147 filename. This file will be opened for reading and the input data
 148 will be read from it.
 149
 150 =item A filehandle
 151
 152 If the C<$input> parameter is a filehandle, the input data will be
 153 read from it.
 154 The string '-' can be used as an alias for standard input.
 155
 156 =item A scalar reference
 157
 158 If C<$input> is a scalar reference, the input data will be read
 159 from C<$$input>.
 160
 161 =item An array reference
 162
 163 If C<$input> is an array reference, the input data will be read from each
 164 element of the array in turn. The action taken by C<inflate> with
 165 each element of the array will depend on the type of data stored
 166 in it. You can mix and match any of the types defined in this list,
 167 excluding other array or hash references.
 168 The complete array will be walked to ensure that it only
 169 contains valid data types before any data is uncompressed.
 170
 171 =item An Input FileGlob string
 172
 173 If C<$input> is a string that is delimited by the characters "<" and ">"
 174 C<inflate> will assume that it is an I<input fileglob string>. The
 175 input is the list of files that match the fileglob.
 176
 177 If the fileglob does not match any files ...
 178
 179 See L<File::GlobMapper|File::GlobMapper> for more details.
 180
 181
 182 =back
 183
 184 If the C<$input> parameter is any other type, C<undef> will be returned.
 185
 186
 187
 188 =head3 The C<$output> parameter
 189
 190 The parameter C<$output> is used to control the destination of the
 191 uncompressed data. This parameter can take one of these forms.
 192
 193 =over 5
 194
 195 =item A filename
 196
 197 If the C<$output> parameter is a simple scalar, it is assumed to be a filename.
 198 This file will be opened for writing and the uncompressed data will be
 199 written to it.
 200
 201 =item A filehandle
 202
 203 If the C<$output> parameter is a filehandle, the uncompressed data will
 204 be written to it.
 205 The string '-' can be used as an alias for standard output.
 206
 207
 208 =item A scalar reference
 209
 210 If C<$output> is a scalar reference, the uncompressed data will be stored
 211 in C<$$output>.
 212
 213
 214 =item A Hash Reference
 215
 216 If C<$output> is a hash reference, the uncompressed data will be written
 217 to C<$output{$input}> as a scalar reference.
 218
 219 When C<$output> is a hash reference, C<$input> must be either a filename or
 220 list of filenames. Anything else is an error.
 221
 222
 223 =item An Array Reference
 224
 225 If C<$output> is an array reference, the uncompressed data will be pushed
 226 onto the array.
 227
 228 =item An Output FileGlob
 229
 230 If C<$output> is a string that is delimited by the characters "<" and ">"
 231 C<inflate> will assume that it is an I<output fileglob string>. The
 232 output is the list of files that match the fileglob.
 233
 234 When C<$output> is an fileglob string, C<$input> must also be a fileglob
 235 string. Anything else is an error.
 236
 237 =back
 238
 239 If the C<$output> parameter is any other type, C<undef> will be returned.
 240
 241 =head2 inflate \%hash [, OPTS]
 242
 243 If the first parameter is a hash reference, C<\%hash>, this will be used to
 244 define both the source of compressed data and to control where the
 245 uncompressed data is output. Each key/value pair in the hash defines a
 246 mapping between an input filename, stored in the key, and an output
 247 file/buffer, stored in the value. Although the input can only be a filename,
 248 there is more flexibility to control the destination of the uncompressed
 249 data. This is determined by the type of the value. Valid types are
 250
 251 =over 5
 252
 253 =item undef
 254
 255 If the value is C<undef> the uncompressed data will be written to the
 256 value as a scalar reference.
 257
 258 =item A filename
 259
 260 If the value is a simple scalar, it is assumed to be a filename. This file will
 261 be opened for writing and the uncompressed data will be written to it.
 262
 263 =item A filehandle
 264
 265 If the value is a filehandle, the uncompressed data will be
 266 written to it.
 267 The string '-' can be used as an alias for standard output.
 268
 269
 270 =item A scalar reference
 271
 272 If the value is a scalar reference, the uncompressed data will be stored
 273 in the buffer that is referenced by the scalar.
 274
 275
 276 =item A Hash Reference
 277
 278 If the value is a hash reference, the uncompressed data will be written
 279 to C<$hash{$input}> as a scalar reference.
 280
 281 =item An Array Reference
 282
 283 If C<$output> is an array reference, the uncompressed data will be pushed
 284 onto the array.
 285
 286 =back
 287
 288 Any other type is a error.
 289
 290 =head2 Notes
 291
 292 When C<$input> maps to multiple files/buffers and C<$output> is a single
 293 file/buffer the uncompressed input files/buffers will all be stored in
 294 C<$output> as a single uncompressed stream.
 295
 296
 297
 298 =head2 Optional Parameters
 299
 300 Unless specified below, the optional parameters for C<inflate>,
 301 C<OPTS>, are the same as those used with the OO interface defined in the
 302 L</"Constructor Options"> section below.
 303
 304 =over 5
 305
 306 =item AutoClose =E<gt> 0|1
 307
 308 This option applies to any input or output data streams to C<inflate>
 309 that are filehandles.
 310
 311 If C<AutoClose> is specified, and the value is true, it will result in all
 312 input and/or output filehandles being closed once C<inflate> has
 313 completed.
 314
 315 This parameter defaults to 0.
 316
 317
 318
 319 =item -Append =E<gt> 0|1
 320
 321 TODO
 322
 323
 324
 325 =back
 326
 327
 328
 329
 330 =head2 Examples
 331
 332 To read the contents of the file C<file1.txt.1950> and write the
 333 compressed data to the file C<file1.txt>.
 334
 335     use strict ;
 336     use warnings ;
 337     use IO::Uncompress::Inflate qw(inflate $InflateError) ;
 338
 339     my $input = "file1.txt.1950";
 340     my $output = "file1.txt";
 341     inflate $input => $output
 342         or die "inflate failed: $InflateError\n";
 343
 344
 345 To read from an existing Perl filehandle, C<$input>, and write the
 346 uncompressed data to a buffer, C<$buffer>.
 347
 348     use strict ;
 349     use warnings ;
 350     use IO::Uncompress::Inflate qw(inflate $InflateError) ;
 351     use IO::File ;
 352
 353     my $input = new IO::File "<file1.txt.1950"
 354         or die "Cannot open 'file1.txt.1950': $!\n" ;
 355     my $buffer ;
 356     inflate $input => \$buffer
 357         or die "inflate failed: $InflateError\n";
 358
 359 To uncompress all files in the directory "/my/home" that match "*.txt.1950" and store the compressed data in the same directory
 360
 361     use strict ;
 362     use warnings ;
 363     use IO::Uncompress::Inflate qw(inflate $InflateError) ;
 364
 365     inflate '</my/home/*.txt.1950>' => '</my/home/#1.txt>'
 366         or die "inflate failed: $InflateError\n";
 367
 368 and if you want to compress each file one at a time, this will do the trick
 369
 370     use strict ;
 371     use warnings ;
 372     use IO::Uncompress::Inflate qw(inflate $InflateError) ;
 373
 374     for my $input ( glob "/my/home/*.txt.1950" )
 375     {
 376         my $output = $input;
 377         $output =~ s/.1950// ;
 378         inflate $input => $output
 379             or die "Error compressing '$input': $InflateError\n";
 380     }
 381
 382 =head1 OO Interface
 383
 384 =head2 Constructor
 385
 386 The format of the constructor for IO::Uncompress::Inflate is shown below
 387
 388
 389     my $z = new IO::Uncompress::Inflate $input [OPTS]
 390         or die "IO::Uncompress::Inflate failed: $InflateError\n";
 391
 392 Returns an C<IO::Uncompress::Inflate> object on success and undef on failure.
 393 The variable C<$InflateError> will contain an error message on failure.
 394
 395 If you are running Perl 5.005 or better the object, C<$z>, returned from
 396 IO::Uncompress::Inflate can be used exactly like an L<IO::File|IO::File> filehandle.
 397 This means that all normal input file operations can be carried out with C<$z>.
 398 For example, to read a line from a compressed file/buffer you can use either
 399 of these forms
 400
 401     $line = $z->getline();
 402     $line = <$z>;
 403
 404 The mandatory parameter C<$input> is used to determine the source of the
 405 compressed data. This parameter can take one of three forms.
 406
 407 =over 5
 408
 409 =item A filename
 410
 411 If the C<$input> parameter is a scalar, it is assumed to be a filename. This
 412 file will be opened for reading and the compressed data will be read from it.
 413
 414 =item A filehandle
 415
 416 If the C<$input> parameter is a filehandle, the compressed data will be
 417 read from it.
 418 The string '-' can be used as an alias for standard input.
 419
 420
 421 =item A scalar reference
 422
 423 If C<$input> is a scalar reference, the compressed data will be read from
 424 C<$$output>.
 425
 426 =back
 427
 428 =head2 Constructor Options
 429
 430
 431 The option names defined below are case insensitive and can be optionally
 432 prefixed by a '-'.  So all of the following are valid
 433
 434     -AutoClose
 435     -autoclose
 436     AUTOCLOSE
 437     autoclose
 438
 439 OPTS is a combination of the following options:
 440
 441 =over 5
 442
 443 =item -AutoClose =E<gt> 0|1
 444
 445 This option is only valid when the C<$input> parameter is a filehandle. If
 446 specified, and the value is true, it will result in the file being closed once
 447 either the C<close> method is called or the IO::Uncompress::Inflate object is
 448 destroyed.
 449
 450 This parameter defaults to 0.
 451
 452 =item -MultiStream =E<gt> 0|1
 453
 454
 455
 456 Allows multiple concatenated compressed streams to be treated as a single
 457 compressed stream. Decompression will stop once either the end of the
 458 file/buffer is reached, an error is encountered (premature eof, corrupt
 459 compressed data) or the end of a stream is not immediately followed by the
 460 start of another stream.
 461
 462 This parameter defaults to 0.
 463
 464
 465
 466 =item -Prime =E<gt> $string
 467
 468 This option will uncompress the contents of C<$string> before processing the
 469 input file/buffer.
 470
 471 This option can be useful when the compressed data is embedded in another
 472 file/data structure and it is not possible to work out where the compressed
 473 data begins without having to read the first few bytes. If this is the case,
 474 the uncompression can be I<primed> with these bytes using this option.
 475
 476 =item -Transparent =E<gt> 0|1
 477
 478 If this option is set and the input file or buffer is not compressed data,
 479 the module will allow reading of it anyway.
 480
 481 This option defaults to 1.
 482
 483 =item -BlockSize =E<gt> $num
 484
 485 When reading the compressed input data, IO::Uncompress::Inflate will read it in blocks
 486 of C<$num> bytes.
 487
 488 This option defaults to 4096.
 489
 490 =item -InputLength =E<gt> $size
 491
 492 When present this option will limit the number of compressed bytes read from
 493 the input file/buffer to C<$size>. This option can be used in the situation
 494 where there is useful data directly after the compressed data stream and you
 495 know beforehand the exact length of the compressed data stream.
 496
 497 This option is mostly used when reading from a filehandle, in which case the
 498 file pointer will be left pointing to the first byte directly after the
 499 compressed data stream.
 500
 501
 502
 503 This option defaults to off.
 504
 505 =item -Append =E<gt> 0|1
 506
 507 This option controls what the C<read> method does with uncompressed data.
 508
 509 If set to 1, all uncompressed data will be appended to the output parameter of
 510 the C<read> method.
 511
 512 If set to 0, the contents of the output parameter of the C<read> method will be
 513 overwritten by the uncompressed data.
 514
 515 Defaults to 0.
 516
 517 =item -Strict =E<gt> 0|1
 518
 519
 520
 521 This option controls whether the extra checks defined below are used when
 522 carrying out the decompression. When Strict is on, the extra tests are carried
 523 out, when Strict is off they are not.
 524
 525 The default for this option is off.
 526
 527
 528
 529
 530
 531 =over 5
 532
 533 =item 1
 534
 535 The ADLER32 checksum field must be present.
 536
 537 =item 2
 538
 539 The value of the ADLER32 field read must match the adler32 value of the
 540 uncompressed data actually contained in the file.
 541
 542 =back
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552 =back
 553
 554 =head2 Examples
 555
 556 TODO
 557
 558 =head1 Methods
 559
 560 =head2 read
 561
 562 Usage is
 563
 564     $status = $z->read($buffer)
 565
 566 Reads a block of compressed data (the size the the compressed block is
 567 determined by the C<Buffer> option in the constructor), uncompresses it and
 568 writes any uncompressed data into C<$buffer>. If the C<Append> parameter is set
 569 in the constructor, the uncompressed data will be appended to the C<$buffer>
 570 parameter. Otherwise C<$buffer> will be overwritten.
 571
 572 Returns the number of uncompressed bytes written to C<$buffer>, zero if eof or
 573 a negative number on error.
 574
 575 =head2 read
 576
 577 Usage is
 578
 579     $status = $z->read($buffer, $length)
 580     $status = $z->read($buffer, $length, $offset)
 581
 582     $status = read($z, $buffer, $length)
 583     $status = read($z, $buffer, $length, $offset)
 584
 585 Attempt to read C<$length> bytes of uncompressed data into C<$buffer>.
 586
 587 The main difference between this form of the C<read> method and the previous
 588 one, is that this one will attempt to return I<exactly> C<$length> bytes. The
 589 only circumstances that this function will not is if end-of-file or an IO error
 590 is encountered.
 591
 592 Returns the number of uncompressed bytes written to C<$buffer>, zero if eof or
 593 a negative number on error.
 594
 595
 596 =head2 getline
 597
 598 Usage is
 599
 600     $line = $z->getline()
 601     $line = <$z>
 602
 603 Reads a single line.
 604
 605 This method fully supports the use of of the variable C<$/>
 606 (or C<$INPUT_RECORD_SEPARATOR> or C<$RS> when C<English> is in use) to
 607 determine what constitutes an end of line. Both paragraph mode and file
 608 slurp mode are supported.
 609
 610
 611 =head2 getc
 612
 613 Usage is
 614
 615     $char = $z->getc()
 616
 617 Read a single character.
 618
 619 =head2 ungetc
 620
 621 Usage is
 622
 623     $char = $z->ungetc($string)
 624
 625
 626 =head2 inflateSync
 627
 628 Usage is
 629
 630     $status = $z->inflateSync()
 631
 632 TODO
 633
 634 =head2 getHeaderInfo
 635
 636 Usage is
 637
 638     $hdr = $z->getHeaderInfo()
 639
 640 TODO
 641
 642
 643
 644
 645
 646 This method returns a hash reference that contains the contents of each of the
 647 header fields defined in RFC1950.
 648
 649
 650
 651
 652
 653
 654
 655 =head2 tell
 656
 657 Usage is
 658
 659     $z->tell()
 660     tell $z
 661
 662 Returns the uncompressed file offset.
 663
 664 =head2 eof
 665
 666 Usage is
 667
 668     $z->eof();
 669     eof($z);
 670
 671
 672
 673 Returns true if the end of the compressed input stream has been reached.
 674
 675
 676
 677 =head2 seek
 678
 679     $z->seek($position, $whence);
 680     seek($z, $position, $whence);
 681
 682
 683
 684
 685 Provides a sub-set of the C<seek> functionality, with the restriction
 686 that it is only legal to seek forward in the input file/buffer.
 687 It is a fatal error to attempt to seek backward.
 688
 689
 690
 691 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
 692 SEEK_CUR or SEEK_END.
 693
 694 Returns 1 on success, 0 on failure.
 695
 696 =head2 binmode
 697
 698 Usage is
 699
 700     $z->binmode
 701     binmode $z ;
 702
 703 This is a noop provided for completeness.
 704
 705 =head2 fileno
 706
 707     $z->fileno()
 708     fileno($z)
 709
 710 If the C<$z> object is associated with a file, this method will return
 711 the underlying filehandle.
 712
 713 If the C<$z> object is is associated with a buffer, this method will
 714 return undef.
 715
 716 =head2 close
 717
 718     $z->close() ;
 719     close $z ;
 720
 721
 722
 723 Closes the output file/buffer.
 724
 725
 726
 727 For most versions of Perl this method will be automatically invoked if
 728 the IO::Uncompress::Inflate object is destroyed (either explicitly or by the
 729 variable with the reference to the object going out of scope). The
 730 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
 731 these cases, the C<close> method will be called automatically, but
 732 not until global destruction of all live objects when the program is
 733 terminating.
 734
 735 Therefore, if you want your scripts to be able to run on all versions
 736 of Perl, you should call C<close> explicitly and not rely on automatic
 737 closing.
 738
 739 Returns true on success, otherwise 0.
 740
 741 If the C<AutoClose> option has been enabled when the IO::Uncompress::Inflate
 742 object was created, and the object is associated with a file, the
 743 underlying file will also be closed.
 744
 745
 746
 747
 748 =head1 Importing
 749
 750 No symbolic constants are required by this IO::Uncompress::Inflate at present.
 751
 752 =over 5
 753
 754 =item :all
 755
 756 Imports C<inflate> and C<$InflateError>.
 757 Same as doing this
 758
 759     use IO::Uncompress::Inflate qw(inflate $InflateError) ;
 760
 761 =back
 762
 763 =head1 EXAMPLES
 764
 765
 766
 767
 768 =head1 SEE ALSO
 769
 770 L<Compress::Zlib>, L<IO::Compress::Gzip>, L<IO::Uncompress::Gunzip>, L<IO::Compress::Deflate>, L<IO::Compress::RawDeflate>, L<IO::Uncompress::RawInflate>, L<IO::Uncompress::AnyInflate>
 771
 772 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
 773
 774 L<File::GlobMapper|File::GlobMapper>, L<Archive::Tar|Archive::Zip>,
 775 L<IO::Zlib|IO::Zlib>
 776
 777 For RFC 1950, 1951 and 1952 see
 778 F<http://www.faqs.org/rfcs/rfc1950.html>,
 779 F<http://www.faqs.org/rfcs/rfc1951.html> and
 780 F<http://www.faqs.org/rfcs/rfc1952.html>
 781
 782 The primary site for the gzip program is F<http://www.gzip.org>.
 783
 784 =head1 AUTHOR
 785
 786 The I<IO::Uncompress::Inflate> module was written by Paul Marquess,
 787 F<pmqs@cpan.org>. The latest copy of the module can be
 788 found on CPAN in F<modules/by-module/Compress/Compress-Zlib-x.x.tar.gz>.
 789
 790 The I<zlib> compression library was written by Jean-loup Gailly
 791 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
 792
 793 The primary site for the I<zlib> compression library is
 794 F<http://www.zlib.org>.
 795
 796 =head1 MODIFICATION HISTORY
 797
 798 See the Changes file.
 799
 800 =head1 COPYRIGHT AND LICENSE
 801
 802
 803 Copyright (c) 2005 Paul Marquess. All rights reserved.
 804 This program is free software; you can redistribute it and/or
 805 modify it under the same terms as Perl itself.
 806
 807
 808