[ Index ]

PHP Cross Reference of Unnamed Project

title

Body

[close]

/se3-unattended/var/se3/unattended/install/linuxaux/opt/perl/lib/5.10.0/i586-linux-thread-multi/IO/Uncompress/ -> RawInflate.pm (source)

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


Generated: Tue Mar 17 22:47:18 2015 Cross-referenced by PHPXref 0.7.1