[Summary view] [Print] [Text view]

   1  package IO::Uncompress::AnyUncompress ;
   2  
   3  use strict;
   4  use warnings;
   5  use bytes;
   6  
   7  use IO::Compress::Base::Common 2.008 qw(createSelfTiedObject);
   8  
   9  use IO::Uncompress::Base 2.008 ;
  10  
  11  
  12  require Exporter ;
  13  
  14  our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $AnyUncompressError);
  15  
  16  $VERSION = '2.008';
  17  $AnyUncompressError = '';
  18  
  19  @ISA = qw( Exporter IO::Uncompress::Base );
  20  @EXPORT_OK = qw( $AnyUncompressError anyuncompress ) ;
  21  %EXPORT_TAGS = %IO::Uncompress::Base::DEFLATE_CONSTANTS ;
  22  push @{ $EXPORT_TAGS{all} }, @EXPORT_OK ;
  23  Exporter::export_ok_tags('all');
  24  
  25  # TODO - allow the user to pick a set of the three formats to allow
  26  #        or just assume want to auto-detect any of the three formats.
  27  
  28  BEGIN
  29  {
  30     eval ' use IO::Uncompress::Adapter::Inflate 2.008 ;';
  31     eval ' use IO::Uncompress::Adapter::Bunzip2 2.008 ;';
  32     eval ' use IO::Uncompress::Adapter::LZO 2.008 ;';
  33     eval ' use IO::Uncompress::Adapter::Lzf 2.008 ;';
  34  
  35     eval ' use IO::Uncompress::Bunzip2 2.008 ;';
  36     eval ' use IO::Uncompress::UnLzop 2.008 ;';
  37     eval ' use IO::Uncompress::Gunzip 2.008 ;';
  38     eval ' use IO::Uncompress::Inflate 2.008 ;';
  39     eval ' use IO::Uncompress::RawInflate 2.008 ;';
  40     eval ' use IO::Uncompress::Unzip 2.008 ;';
  41     eval ' use IO::Uncompress::UnLzf 2.008 ;';
  42  }
  43  
  44  sub new
  45  {
  46      my $class = shift ;
  47      my $obj = createSelfTiedObject($class, \$AnyUncompressError);
  48      $obj->_create(undef, 0, @_);
  49  }
  50  
  51  sub anyuncompress
  52  {
  53      my $obj = createSelfTiedObject(undef, \$AnyUncompressError);
  54      return $obj->_inf(@_) ;
  55  }
  56  
  57  sub getExtraParams
  58  {
  59      use IO::Compress::Base::Common 2.008 qw(:Parse);
  60      return ( 'RawInflate' => [1, 1, Parse_boolean,  0] ) ;
  61  }
  62  
  63  sub ckParams
  64  {
  65      my $self = shift ;
  66      my $got = shift ;
  67  
  68      # any always needs both crc32 and adler32
  69      $got->value('CRC32' => 1);
  70      $got->value('ADLER32' => 1);
  71  
  72      return 1;
  73  }
  74  
  75  sub mkUncomp
  76  {
  77      my $self = shift ;
  78      my $class = shift ;
  79      my $got = shift ;
  80  
  81      my $magic ;
  82  
  83      # try zlib first
  84      if (defined $IO::Uncompress::RawInflate::VERSION )
  85      {
  86          my ($obj, $errstr, $errno) = IO::Uncompress::Adapter::Inflate::mkUncompObject();
  87  
  88          return $self->saveErrorString(undef, $errstr, $errno)
  89              if ! defined $obj;
  90  
  91          *$self->{Uncomp} = $obj;
  92          
  93          my @possible = qw( Inflate Gunzip Unzip );
  94          unshift @possible, 'RawInflate' 
  95              if $got->value('RawInflate');
  96  
  97          $magic = $self->ckMagic( @possible );
  98          
  99          if ($magic) {
 100              *$self->{Info} = $self->readHeader($magic)
 101                  or return undef ;
 102  
 103              return 1;
 104          }
 105       }
 106  
 107       if (defined $IO::Uncompress::Bunzip2::VERSION and
 108           $magic = $self->ckMagic('Bunzip2')) {
 109          *$self->{Info} = $self->readHeader($magic)
 110              or return undef ;
 111  
 112          my ($obj, $errstr, $errno) = IO::Uncompress::Adapter::Bunzip2::mkUncompObject();
 113  
 114          return $self->saveErrorString(undef, $errstr, $errno)
 115              if ! defined $obj;
 116  
 117          *$self->{Uncomp} = $obj;
 118  
 119           return 1;
 120       }
 121  
 122       if (defined $IO::Uncompress::UnLzop::VERSION and
 123              $magic = $self->ckMagic('UnLzop')) {
 124  
 125          *$self->{Info} = $self->readHeader($magic)
 126              or return undef ;
 127  
 128          my ($obj, $errstr, $errno) = IO::Uncompress::Adapter::LZO::mkUncompObject();
 129  
 130          return $self->saveErrorString(undef, $errstr, $errno)
 131              if ! defined $obj;
 132  
 133          *$self->{Uncomp} = $obj;
 134  
 135           return 1;
 136       }
 137  
 138       if (defined $IO::Uncompress::UnLzf::VERSION and
 139              $magic = $self->ckMagic('UnLzf')) {
 140  
 141          *$self->{Info} = $self->readHeader($magic)
 142              or return undef ;
 143  
 144          my ($obj, $errstr, $errno) = IO::Uncompress::Adapter::Lzf::mkUncompObject();
 145  
 146          return $self->saveErrorString(undef, $errstr, $errno)
 147              if ! defined $obj;
 148  
 149          *$self->{Uncomp} = $obj;
 150  
 151           return 1;
 152       }
 153  
 154       return 0 ;
 155  }
 156  
 157  
 158  
 159  sub ckMagic
 160  {
 161      my $self = shift;
 162      my @names = @_ ;
 163  
 164      my $keep = ref $self ;
 165      for my $class ( map { "IO::Uncompress::$_" } @names)
 166      {
 167          bless $self => $class;
 168          my $magic = $self->ckMagic();
 169  
 170          if ($magic)
 171          {
 172              #bless $self => $class;
 173              return $magic ;
 174          }
 175  
 176          $self->pushBack(*$self->{HeaderPending})  ;
 177          *$self->{HeaderPending} = ''  ;
 178      }    
 179  
 180      bless $self => $keep;
 181      return undef;
 182  }
 183  
 184  1 ;
 185  
 186  __END__
 187  
 188  
 189  =head1 NAME
 190  
 191  
 192  IO::Uncompress::AnyUncompress - Uncompress gzip, zip, bzip2 or lzop file/buffer
 193  
 194  
 195  =head1 SYNOPSIS
 196  
 197      use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
 198  
 199      my $status = anyuncompress $input => $output [,OPTS]
 200          or die "anyuncompress failed: $AnyUncompressError\n";
 201  
 202      my $z = new IO::Uncompress::AnyUncompress $input [OPTS] 
 203          or die "anyuncompress failed: $AnyUncompressError\n";
 204  
 205      $status = $z->read($buffer)
 206      $status = $z->read($buffer, $length)
 207      $status = $z->read($buffer, $length, $offset)
 208      $line = $z->getline()
 209      $char = $z->getc()
 210      $char = $z->ungetc()
 211      $char = $z->opened()
 212  
 213      $data = $z->trailingData()
 214      $status = $z->nextStream()
 215      $data = $z->getHeaderInfo()
 216      $z->tell()
 217      $z->seek($position, $whence)
 218      $z->binmode()
 219      $z->fileno()
 220      $z->eof()
 221      $z->close()
 222  
 223      $AnyUncompressError ;
 224  
 225      # IO::File mode
 226  
 227      <$z>
 228      read($z, $buffer);
 229      read($z, $buffer, $length);
 230      read($z, $buffer, $length, $offset);
 231      tell($z)
 232      seek($z, $position, $whence)
 233      binmode($z)
 234      fileno($z)
 235      eof($z)
 236      close($z)
 237  
 238  
 239  =head1 DESCRIPTION
 240  
 241  
 242  This module provides a Perl interface that allows the reading of
 243  files/buffers that have been compressed with a variety of compression
 244  libraries.
 245  
 246  The formats supported are:
 247  
 248  =over 5
 249  
 250  =item RFC 1950
 251  
 252  =item RFC 1951 (optionally)
 253  
 254  =item gzip (RFC 1952)
 255  
 256  =item zip
 257  
 258  =item bzip2
 259  
 260  =item lzop
 261  
 262  =item lzf
 263  
 264  =back
 265  
 266  The module will auto-detect which, if any, of the supported
 267  compression formats is being used.
 268  
 269  
 270  
 271  
 272  =head1 Functional Interface
 273  
 274  A top-level function, C<anyuncompress>, is provided to carry out
 275  "one-shot" uncompression between buffers and/or files. For finer
 276  control over the uncompression process, see the L</"OO Interface">
 277  section.
 278  
 279      use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
 280  
 281      anyuncompress $input => $output [,OPTS] 
 282          or die "anyuncompress failed: $AnyUncompressError\n";
 283  
 284  
 285  
 286  The functional interface needs Perl5.005 or better.
 287  
 288  
 289  =head2 anyuncompress $input => $output [, OPTS]
 290  
 291  
 292  C<anyuncompress> expects at least two parameters, C<$input> and C<$output>.
 293  
 294  =head3 The C<$input> parameter
 295  
 296  The parameter, C<$input>, is used to define the source of
 297  the compressed data. 
 298  
 299  It can take one of the following forms:
 300  
 301  =over 5
 302  
 303  =item A filename
 304  
 305  If the C<$input> parameter is a simple scalar, it is assumed to be a
 306  filename. This file will be opened for reading and the input data
 307  will be read from it.
 308  
 309  =item A filehandle
 310  
 311  If the C<$input> parameter is a filehandle, the input data will be
 312  read from it.
 313  The string '-' can be used as an alias for standard input.
 314  
 315  =item A scalar reference 
 316  
 317  If C<$input> is a scalar reference, the input data will be read
 318  from C<$$input>.
 319  
 320  =item An array reference 
 321  
 322  If C<$input> is an array reference, each element in the array must be a
 323  filename.
 324  
 325  The input data will be read from each file in turn. 
 326  
 327  The complete array will be walked to ensure that it only
 328  contains valid filenames before any data is uncompressed.
 329  
 330  
 331  
 332  =item An Input FileGlob string
 333  
 334  If C<$input> is a string that is delimited by the characters "<" and ">"
 335  C<anyuncompress> will assume that it is an I<input fileglob string>. The
 336  input is the list of files that match the fileglob.
 337  
 338  If the fileglob does not match any files ...
 339  
 340  See L<File::GlobMapper|File::GlobMapper> for more details.
 341  
 342  
 343  =back
 344  
 345  If the C<$input> parameter is any other type, C<undef> will be returned.
 346  
 347  
 348  
 349  =head3 The C<$output> parameter
 350  
 351  The parameter C<$output> is used to control the destination of the
 352  uncompressed data. This parameter can take one of these forms.
 353  
 354  =over 5
 355  
 356  =item A filename
 357  
 358  If the C<$output> parameter is a simple scalar, it is assumed to be a
 359  filename.  This file will be opened for writing and the uncompressed
 360  data will be written to it.
 361  
 362  =item A filehandle
 363  
 364  If the C<$output> parameter is a filehandle, the uncompressed data
 365  will be written to it.
 366  The string '-' can be used as an alias for standard output.
 367  
 368  
 369  =item A scalar reference 
 370  
 371  If C<$output> is a scalar reference, the uncompressed data will be
 372  stored in C<$$output>.
 373  
 374  
 375  
 376  =item An Array Reference
 377  
 378  If C<$output> is an array reference, the uncompressed data will be
 379  pushed onto the array.
 380  
 381  =item An Output FileGlob
 382  
 383  If C<$output> is a string that is delimited by the characters "<" and ">"
 384  C<anyuncompress> will assume that it is an I<output fileglob string>. The
 385  output is the list of files that match the fileglob.
 386  
 387  When C<$output> is an fileglob string, C<$input> must also be a fileglob
 388  string. Anything else is an error.
 389  
 390  =back
 391  
 392  If the C<$output> parameter is any other type, C<undef> will be returned.
 393  
 394  
 395  
 396  =head2 Notes
 397  
 398  
 399  When C<$input> maps to multiple compressed files/buffers and C<$output> is
 400  a single file/buffer, after uncompression C<$output> will contain a
 401  concatenation of all the uncompressed data from each of the input
 402  files/buffers.
 403  
 404  
 405  
 406  
 407  
 408  =head2 Optional Parameters
 409  
 410  Unless specified below, the optional parameters for C<anyuncompress>,
 411  C<OPTS>, are the same as those used with the OO interface defined in the
 412  L</"Constructor Options"> section below.
 413  
 414  =over 5
 415  
 416  =item C<< AutoClose => 0|1 >>
 417  
 418  This option applies to any input or output data streams to 
 419  C<anyuncompress> that are filehandles.
 420  
 421  If C<AutoClose> is specified, and the value is true, it will result in all
 422  input and/or output filehandles being closed once C<anyuncompress> has
 423  completed.
 424  
 425  This parameter defaults to 0.
 426  
 427  
 428  =item C<< BinModeOut => 0|1 >>
 429  
 430  When writing to a file or filehandle, set C<binmode> before writing to the
 431  file.
 432  
 433  Defaults to 0.
 434  
 435  
 436  
 437  
 438  
 439  =item C<< Append => 0|1 >>
 440  
 441  TODO
 442  
 443  =item C<< MultiStream => 0|1 >>
 444  
 445  
 446  If the input file/buffer contains multiple compressed data streams, this
 447  option will uncompress the whole lot as a single data stream.
 448  
 449  Defaults to 0.
 450  
 451  
 452  
 453  
 454  
 455  =item C<< TrailingData => $scalar >>
 456  
 457  Returns the data, if any, that is present immediately after the compressed
 458  data stream once uncompression is complete. 
 459  
 460  This option can be used when there is useful information immediately
 461  following the compressed data stream, and you don't know the length of the
 462  compressed data stream.
 463  
 464  If the input is a buffer, C<trailingData> will return everything from the
 465  end of the compressed data stream to the end of the buffer.
 466  
 467  If the input is a filehandle, C<trailingData> will return the data that is
 468  left in the filehandle input buffer once the end of the compressed data
 469  stream has been reached. You can then use the filehandle to read the rest
 470  of the input file. 
 471  
 472  Don't bother using C<trailingData> if the input is a filename.
 473  
 474  
 475  
 476  If you know the length of the compressed data stream before you start
 477  uncompressing, you can avoid having to use C<trailingData> by setting the
 478  C<InputLength> option.
 479  
 480  
 481  
 482  =back
 483  
 484  
 485  
 486  
 487  =head2 Examples
 488  
 489  To read the contents of the file C<file1.txt.Compressed> and write the
 490  compressed data to the file C<file1.txt>.
 491  
 492      use strict ;
 493      use warnings ;
 494      use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
 495  
 496      my $input = "file1.txt.Compressed";
 497      my $output = "file1.txt";
 498      anyuncompress $input => $output
 499          or die "anyuncompress failed: $AnyUncompressError\n";
 500  
 501  
 502  To read from an existing Perl filehandle, C<$input>, and write the
 503  uncompressed data to a buffer, C<$buffer>.
 504  
 505      use strict ;
 506      use warnings ;
 507      use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
 508      use IO::File ;
 509  
 510      my $input = new IO::File "<file1.txt.Compressed"
 511          or die "Cannot open 'file1.txt.Compressed': $!\n" ;
 512      my $buffer ;
 513      anyuncompress $input => \$buffer 
 514          or die "anyuncompress failed: $AnyUncompressError\n";
 515  
 516  To uncompress all files in the directory "/my/home" that match "*.txt.Compressed" and store the compressed data in the same directory
 517  
 518      use strict ;
 519      use warnings ;
 520      use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
 521  
 522      anyuncompress '</my/home/*.txt.Compressed>' => '</my/home/#1.txt>'
 523          or die "anyuncompress failed: $AnyUncompressError\n";
 524  
 525  and if you want to compress each file one at a time, this will do the trick
 526  
 527      use strict ;
 528      use warnings ;
 529      use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
 530  
 531      for my $input ( glob "/my/home/*.txt.Compressed" )
 532      {
 533          my $output = $input;
 534          $output =~ s/.Compressed// ;
 535          anyuncompress $input => $output 
 536              or die "Error compressing '$input': $AnyUncompressError\n";
 537      }
 538  
 539  =head1 OO Interface
 540  
 541  =head2 Constructor
 542  
 543  The format of the constructor for IO::Uncompress::AnyUncompress is shown below
 544  
 545  
 546      my $z = new IO::Uncompress::AnyUncompress $input [OPTS]
 547          or die "IO::Uncompress::AnyUncompress failed: $AnyUncompressError\n";
 548  
 549  Returns an C<IO::Uncompress::AnyUncompress> object on success and undef on failure.
 550  The variable C<$AnyUncompressError> will contain an error message on failure.
 551  
 552  If you are running Perl 5.005 or better the object, C<$z>, returned from
 553  IO::Uncompress::AnyUncompress can be used exactly like an L<IO::File|IO::File> filehandle.
 554  This means that all normal input file operations can be carried out with
 555  C<$z>.  For example, to read a line from a compressed file/buffer you can
 556  use either of these forms
 557  
 558      $line = $z->getline();
 559      $line = <$z>;
 560  
 561  The mandatory parameter C<$input> is used to determine the source of the
 562  compressed data. This parameter can take one of three forms.
 563  
 564  =over 5
 565  
 566  =item A filename
 567  
 568  If the C<$input> parameter is a scalar, it is assumed to be a filename. This
 569  file will be opened for reading and the compressed data will be read from it.
 570  
 571  =item A filehandle
 572  
 573  If the C<$input> parameter is a filehandle, the compressed data will be
 574  read from it.
 575  The string '-' can be used as an alias for standard input.
 576  
 577  
 578  =item A scalar reference 
 579  
 580  If C<$input> is a scalar reference, the compressed data will be read from
 581  C<$$output>.
 582  
 583  =back
 584  
 585  =head2 Constructor Options
 586  
 587  
 588  The option names defined below are case insensitive and can be optionally
 589  prefixed by a '-'.  So all of the following are valid
 590  
 591      -AutoClose
 592      -autoclose
 593      AUTOCLOSE
 594      autoclose
 595  
 596  OPTS is a combination of the following options:
 597  
 598  =over 5
 599  
 600  =item C<< AutoClose => 0|1 >>
 601  
 602  This option is only valid when the C<$input> parameter is a filehandle. If
 603  specified, and the value is true, it will result in the file being closed once
 604  either the C<close> method is called or the IO::Uncompress::AnyUncompress object is
 605  destroyed.
 606  
 607  This parameter defaults to 0.
 608  
 609  =item C<< MultiStream => 0|1 >>
 610  
 611  
 612  
 613  Allows multiple concatenated compressed streams to be treated as a single
 614  compressed stream. Decompression will stop once either the end of the
 615  file/buffer is reached, an error is encountered (premature eof, corrupt
 616  compressed data) or the end of a stream is not immediately followed by the
 617  start of another stream.
 618  
 619  This parameter defaults to 0.
 620  
 621  
 622  =item C<< Prime => $string >>
 623  
 624  This option will uncompress the contents of C<$string> before processing the
 625  input file/buffer.
 626  
 627  This option can be useful when the compressed data is embedded in another
 628  file/data structure and it is not possible to work out where the compressed
 629  data begins without having to read the first few bytes. If this is the
 630  case, the uncompression can be I<primed> with these bytes using this
 631  option.
 632  
 633  =item C<< Transparent => 0|1 >>
 634  
 635  If this option is set and the input file/buffer is not compressed data,
 636  the module will allow reading of it anyway.
 637  
 638  In addition, if the input file/buffer does contain compressed data and
 639  there is non-compressed data immediately following it, setting this option
 640  will make this module treat the whole file/bufffer as a single data stream.
 641  
 642  This option defaults to 1.
 643  
 644  =item C<< BlockSize => $num >>
 645  
 646  When reading the compressed input data, IO::Uncompress::AnyUncompress will read it in
 647  blocks of C<$num> bytes.
 648  
 649  This option defaults to 4096.
 650  
 651  =item C<< InputLength => $size >>
 652  
 653  When present this option will limit the number of compressed bytes read
 654  from the input file/buffer to C<$size>. This option can be used in the
 655  situation where there is useful data directly after the compressed data
 656  stream and you know beforehand the exact length of the compressed data
 657  stream. 
 658  
 659  This option is mostly used when reading from a filehandle, in which case
 660  the file pointer will be left pointing to the first byte directly after the
 661  compressed data stream.
 662  
 663  
 664  
 665  This option defaults to off.
 666  
 667  =item C<< Append => 0|1 >>
 668  
 669  This option controls what the C<read> method does with uncompressed data.
 670  
 671  If set to 1, all uncompressed data will be appended to the output parameter
 672  of the C<read> method.
 673  
 674  If set to 0, the contents of the output parameter of the C<read> method
 675  will be overwritten by the uncompressed data.
 676  
 677  Defaults to 0.
 678  
 679  =item C<< Strict => 0|1 >>
 680  
 681  
 682  
 683  This option controls whether the extra checks defined below are used when
 684  carrying out the decompression. When Strict is on, the extra tests are
 685  carried out, when Strict is off they are not.
 686  
 687  The default for this option is off.
 688  
 689  
 690  
 691  
 692  
 693  
 694  
 695  
 696  
 697  
 698  
 699  =item C<< RawInflate => 0|1 >>
 700  
 701  When auto-detecting the compressed format, try to test for raw-deflate (RFC
 702  1951) content using the C<IO::Uncompress::RawInflate> module. 
 703  
 704  The reason this is not default behaviour is because RFC 1951 content can
 705  only be detected by attempting to uncompress it. This process is error
 706  prone and can result is false positives.
 707  
 708  Defaults to 0.
 709  
 710  
 711  
 712  
 713  
 714  
 715  =back
 716  
 717  =head2 Examples
 718  
 719  TODO
 720  
 721  =head1 Methods 
 722  
 723  =head2 read
 724  
 725  Usage is
 726  
 727      $status = $z->read($buffer)
 728  
 729  Reads a block of compressed data (the size the the compressed block is
 730  determined by the C<Buffer> option in the constructor), uncompresses it and
 731  writes any uncompressed data into C<$buffer>. If the C<Append> parameter is
 732  set in the constructor, the uncompressed data will be appended to the
 733  C<$buffer> parameter. Otherwise C<$buffer> will be overwritten.
 734  
 735  Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
 736  or a negative number on error.
 737  
 738  =head2 read
 739  
 740  Usage is
 741  
 742      $status = $z->read($buffer, $length)
 743      $status = $z->read($buffer, $length, $offset)
 744  
 745      $status = read($z, $buffer, $length)
 746      $status = read($z, $buffer, $length, $offset)
 747  
 748  Attempt to read C<$length> bytes of uncompressed data into C<$buffer>.
 749  
 750  The main difference between this form of the C<read> method and the
 751  previous one, is that this one will attempt to return I<exactly> C<$length>
 752  bytes. The only circumstances that this function will not is if end-of-file
 753  or an IO error is encountered.
 754  
 755  Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
 756  or a negative number on error.
 757  
 758  
 759  =head2 getline
 760  
 761  Usage is
 762  
 763      $line = $z->getline()
 764      $line = <$z>
 765  
 766  Reads a single line. 
 767  
 768  This method fully supports the use of of the variable C<$/> (or
 769  C<$INPUT_RECORD_SEPARATOR> or C<$RS> when C<English> is in use) to
 770  determine what constitutes an end of line. Paragraph mode, record mode and
 771  file slurp mode are all supported. 
 772  
 773  
 774  =head2 getc
 775  
 776  Usage is 
 777  
 778      $char = $z->getc()
 779  
 780  Read a single character.
 781  
 782  =head2 ungetc
 783  
 784  Usage is
 785  
 786      $char = $z->ungetc($string)
 787  
 788  
 789  
 790  
 791  =head2 getHeaderInfo
 792  
 793  Usage is
 794  
 795      $hdr  = $z->getHeaderInfo();
 796      @hdrs = $z->getHeaderInfo();
 797  
 798  This method returns either a hash reference (in scalar context) or a list
 799  or hash references (in array context) that contains information about each
 800  of the header fields in the compressed data stream(s).
 801  
 802  
 803  
 804  
 805  =head2 tell
 806  
 807  Usage is
 808  
 809      $z->tell()
 810      tell $z
 811  
 812  Returns the uncompressed file offset.
 813  
 814  =head2 eof
 815  
 816  Usage is
 817  
 818      $z->eof();
 819      eof($z);
 820  
 821  
 822  
 823  Returns true if the end of the compressed input stream has been reached.
 824  
 825  
 826  
 827  =head2 seek
 828  
 829      $z->seek($position, $whence);
 830      seek($z, $position, $whence);
 831  
 832  
 833  
 834  
 835  Provides a sub-set of the C<seek> functionality, with the restriction
 836  that it is only legal to seek forward in the input file/buffer.
 837  It is a fatal error to attempt to seek backward.
 838  
 839  
 840  
 841  The C<$whence> parameter takes one the usual values, namely SEEK_SET,
 842  SEEK_CUR or SEEK_END.
 843  
 844  Returns 1 on success, 0 on failure.
 845  
 846  =head2 binmode
 847  
 848  Usage is
 849  
 850      $z->binmode
 851      binmode $z ;
 852  
 853  This is a noop provided for completeness.
 854  
 855  =head2 opened
 856  
 857      $z->opened()
 858  
 859  Returns true if the object currently refers to a opened file/buffer. 
 860  
 861  =head2 autoflush
 862  
 863      my $prev = $z->autoflush()
 864      my $prev = $z->autoflush(EXPR)
 865  
 866  If the C<$z> object is associated with a file or a filehandle, this method
 867  returns the current autoflush setting for the underlying filehandle. If
 868  C<EXPR> is present, and is non-zero, it will enable flushing after every
 869  write/print operation.
 870  
 871  If C<$z> is associated with a buffer, this method has no effect and always
 872  returns C<undef>.
 873  
 874  B<Note> that the special variable C<$|> B<cannot> be used to set or
 875  retrieve the autoflush setting.
 876  
 877  =head2 input_line_number
 878  
 879      $z->input_line_number()
 880      $z->input_line_number(EXPR)
 881  
 882  
 883  
 884  Returns the current uncompressed line number. If C<EXPR> is present it has
 885  the effect of setting the line number. Note that setting the line number
 886  does not change the current position within the file/buffer being read.
 887  
 888  The contents of C<$/> are used to to determine what constitutes a line
 889  terminator.
 890  
 891  
 892  
 893  =head2 fileno
 894  
 895      $z->fileno()
 896      fileno($z)
 897  
 898  If the C<$z> object is associated with a file or a filehandle, this method
 899  will return the underlying file descriptor.
 900  
 901  If the C<$z> object is is associated with a buffer, this method will
 902  return undef.
 903  
 904  =head2 close
 905  
 906      $z->close() ;
 907      close $z ;
 908  
 909  
 910  
 911  Closes the output file/buffer. 
 912  
 913  
 914  
 915  For most versions of Perl this method will be automatically invoked if
 916  the IO::Uncompress::AnyUncompress object is destroyed (either explicitly or by the
 917  variable with the reference to the object going out of scope). The
 918  exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
 919  these cases, the C<close> method will be called automatically, but
 920  not until global destruction of all live objects when the program is
 921  terminating.
 922  
 923  Therefore, if you want your scripts to be able to run on all versions
 924  of Perl, you should call C<close> explicitly and not rely on automatic
 925  closing.
 926  
 927  Returns true on success, otherwise 0.
 928  
 929  If the C<AutoClose> option has been enabled when the IO::Uncompress::AnyUncompress
 930  object was created, and the object is associated with a file, the
 931  underlying file will also be closed.
 932  
 933  
 934  
 935  
 936  =head2 nextStream
 937  
 938  Usage is
 939  
 940      my $status = $z->nextStream();
 941  
 942  Skips to the next compressed data stream in the input file/buffer. If a new
 943  compressed data stream is found, the eof marker will be cleared and C<$.>
 944  will be reset to 0.
 945  
 946  Returns 1 if a new stream was found, 0 if none was found, and -1 if an
 947  error was encountered.
 948  
 949  =head2 trailingData
 950  
 951  Usage is
 952  
 953      my $data = $z->trailingData();
 954  
 955  Returns the data, if any, that is present immediately after the compressed
 956  data stream once uncompression is complete. It only makes sense to call
 957  this method once the end of the compressed data stream has been
 958  encountered.
 959  
 960  This option can be used when there is useful information immediately
 961  following the compressed data stream, and you don't know the length of the
 962  compressed data stream.
 963  
 964  If the input is a buffer, C<trailingData> will return everything from the
 965  end of the compressed data stream to the end of the buffer.
 966  
 967  If the input is a filehandle, C<trailingData> will return the data that is
 968  left in the filehandle input buffer once the end of the compressed data
 969  stream has been reached. You can then use the filehandle to read the rest
 970  of the input file. 
 971  
 972  Don't bother using C<trailingData> if the input is a filename.
 973  
 974  
 975  
 976  If you know the length of the compressed data stream before you start
 977  uncompressing, you can avoid having to use C<trailingData> by setting the
 978  C<InputLength> option in the constructor.
 979  
 980  =head1 Importing 
 981  
 982  No symbolic constants are required by this IO::Uncompress::AnyUncompress at present. 
 983  
 984  =over 5
 985  
 986  =item :all
 987  
 988  Imports C<anyuncompress> and C<$AnyUncompressError>.
 989  Same as doing this
 990  
 991      use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
 992  
 993  =back
 994  
 995  =head1 EXAMPLES
 996  
 997  
 998  
 999  
1000  =head1 SEE ALSO
1001  
1002  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::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Uncompress::AnyInflate>
1003  
1004  L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1005  
1006  L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1007  L<Archive::Tar|Archive::Tar>,
1008  L<IO::Zlib|IO::Zlib>
1009  
1010  
1011  
1012  
1013  
1014  =head1 AUTHOR
1015  
1016  This module was written by Paul Marquess, F<pmqs@cpan.org>. 
1017  
1018  
1019  
1020  =head1 MODIFICATION HISTORY
1021  
1022  See the Changes file.
1023  
1024  =head1 COPYRIGHT AND LICENSE
1025  
1026  Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
1027  
1028  This program is free software; you can redistribute it and/or
1029  modify it under the same terms as Perl itself.
1030