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

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