[Summary view] [Print] [Text view]

   1  
   2  package IO::Compress::Gzip ;
   3  
   4  require 5.004 ;
   5  
   6  use strict ;
   7  use warnings;
   8  use bytes;
   9  
  10  
  11  use IO::Compress::RawDeflate 2.008 ;
  12  
  13  use Compress::Raw::Zlib  2.008 ;
  14  use IO::Compress::Base::Common  2.008 qw(:Status :Parse createSelfTiedObject);
  15  use IO::Compress::Gzip::Constants 2.008 ;
  16  use IO::Compress::Zlib::Extra 2.008 ;
  17  
  18  BEGIN
  19  {
  20      if (defined &utf8::downgrade ) 
  21        { *noUTF8 = \&utf8::downgrade }
  22      else
  23        { *noUTF8 = sub {} }  
  24  }
  25  
  26  require Exporter ;
  27  
  28  our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $GzipError);
  29  
  30  $VERSION = '2.008';
  31  $GzipError = '' ;
  32  
  33  @ISA    = qw(Exporter IO::Compress::RawDeflate);
  34  @EXPORT_OK = qw( $GzipError gzip ) ;
  35  %EXPORT_TAGS = %IO::Compress::RawDeflate::DEFLATE_CONSTANTS ;
  36  push @{ $EXPORT_TAGS{all} }, @EXPORT_OK ;
  37  Exporter::export_ok_tags('all');
  38  
  39  sub new
  40  {
  41      my $class = shift ;
  42  
  43      my $obj = createSelfTiedObject($class, \$GzipError);
  44  
  45      $obj->_create(undef, @_);
  46  }
  47  
  48  
  49  sub gzip
  50  {
  51      my $obj = createSelfTiedObject(undef, \$GzipError);
  52      return $obj->_def(@_);
  53  }
  54  
  55  #sub newHeader
  56  #{
  57  #    my $self = shift ;
  58  #    #return GZIP_MINIMUM_HEADER ;
  59  #    return $self->mkHeader(*$self->{Got});
  60  #}
  61  
  62  sub getExtraParams
  63  {
  64      my $self = shift ;
  65  
  66      return (
  67              # zlib behaviour
  68              $self->getZlibParams(),
  69  
  70              # Gzip header fields
  71              'Minimal'   => [0, 1, Parse_boolean,   0],
  72              'Comment'   => [0, 1, Parse_any,       undef],
  73              'Name'      => [0, 1, Parse_any,       undef],
  74              'Time'      => [0, 1, Parse_any,       undef],
  75              'TextFlag'  => [0, 1, Parse_boolean,   0],
  76              'HeaderCRC' => [0, 1, Parse_boolean,   0],
  77              'OS_Code'   => [0, 1, Parse_unsigned,  $Compress::Raw::Zlib::gzip_os_code],
  78              'ExtraField'=> [0, 1, Parse_any,       undef],
  79              'ExtraFlags'=> [0, 1, Parse_any,       undef],
  80  
  81          );
  82  }
  83  
  84  
  85  sub ckParams
  86  {
  87      my $self = shift ;
  88      my $got = shift ;
  89  
  90      # gzip always needs crc32
  91      $got->value('CRC32' => 1);
  92  
  93      return 1
  94          if $got->value('Merge') ;
  95  
  96      my $strict = $got->value('Strict') ;
  97  
  98  
  99      {
 100          if (! $got->parsed('Time') ) {
 101              # Modification time defaults to now.
 102              $got->value('Time' => time) ;
 103          }
 104  
 105          # Check that the Name & Comment don't have embedded NULLs
 106          # Also check that they only contain ISO 8859-1 chars.
 107          if ($got->parsed('Name') && defined $got->value('Name')) {
 108              my $name = $got->value('Name');
 109                  
 110              return $self->saveErrorString(undef, "Null Character found in Name",
 111                                                  Z_DATA_ERROR)
 112                  if $strict && $name =~ /\x00/ ;
 113  
 114              return $self->saveErrorString(undef, "Non ISO 8859-1 Character found in Name",
 115                                                  Z_DATA_ERROR)
 116                  if $strict && $name =~ /$GZIP_FNAME_INVALID_CHAR_RE/o ;
 117          }
 118  
 119          if ($got->parsed('Comment') && defined $got->value('Comment')) {
 120              my $comment = $got->value('Comment');
 121  
 122              return $self->saveErrorString(undef, "Null Character found in Comment",
 123                                                  Z_DATA_ERROR)
 124                  if $strict && $comment =~ /\x00/ ;
 125  
 126              return $self->saveErrorString(undef, "Non ISO 8859-1 Character found in Comment",
 127                                                  Z_DATA_ERROR)
 128                  if $strict && $comment =~ /$GZIP_FCOMMENT_INVALID_CHAR_RE/o;
 129          }
 130  
 131          if ($got->parsed('OS_Code') ) {
 132              my $value = $got->value('OS_Code');
 133  
 134              return $self->saveErrorString(undef, "OS_Code must be between 0 and 255, got '$value'")
 135                  if $value < 0 || $value > 255 ;
 136              
 137          }
 138  
 139          # gzip only supports Deflate at present
 140          $got->value('Method' => Z_DEFLATED) ;
 141  
 142          if ( ! $got->parsed('ExtraFlags')) {
 143              $got->value('ExtraFlags' => 2) 
 144                  if $got->value('Level') == Z_BEST_SPEED ;
 145              $got->value('ExtraFlags' => 4) 
 146                  if $got->value('Level') == Z_BEST_COMPRESSION ;
 147          }
 148  
 149          my $data = $got->value('ExtraField') ;
 150          if (defined $data) {
 151              my $bad = IO::Compress::Zlib::Extra::parseExtraField($data, $strict, 1) ;
 152              return $self->saveErrorString(undef, "Error with ExtraField Parameter: $bad", Z_DATA_ERROR)
 153                  if $bad ;
 154  
 155              $got->value('ExtraField', $data) ;
 156          }
 157      }
 158  
 159      return 1;
 160  }
 161  
 162  sub mkTrailer
 163  {
 164      my $self = shift ;
 165      return pack("V V", *$self->{Compress}->crc32(), 
 166                         *$self->{UnCompSize}->get32bit());
 167  }
 168  
 169  sub getInverseClass
 170  {
 171      return ('IO::Uncompress::Gunzip',
 172                  \$IO::Uncompress::Gunzip::GunzipError);
 173  }
 174  
 175  sub getFileInfo
 176  {
 177      my $self = shift ;
 178      my $params = shift;
 179      my $filename = shift ;
 180  
 181      my $defaultTime = (stat($filename))[9] ;
 182  
 183      $params->value('Name' => $filename)
 184          if ! $params->parsed('Name') ;
 185  
 186      $params->value('Time' => $defaultTime) 
 187          if ! $params->parsed('Time') ;
 188  }
 189  
 190  
 191  sub mkHeader
 192  {
 193      my $self = shift ;
 194      my $param = shift ;
 195  
 196      # stort-circuit if a minimal header is requested.
 197      return GZIP_MINIMUM_HEADER if $param->value('Minimal') ;
 198  
 199      # METHOD
 200      my $method = $param->valueOrDefault('Method', GZIP_CM_DEFLATED) ;
 201  
 202      # FLAGS
 203      my $flags       = GZIP_FLG_DEFAULT ;
 204      $flags |= GZIP_FLG_FTEXT    if $param->value('TextFlag') ;
 205      $flags |= GZIP_FLG_FHCRC    if $param->value('HeaderCRC') ;
 206      $flags |= GZIP_FLG_FEXTRA   if $param->wantValue('ExtraField') ;
 207      $flags |= GZIP_FLG_FNAME    if $param->wantValue('Name') ;
 208      $flags |= GZIP_FLG_FCOMMENT if $param->wantValue('Comment') ;
 209      
 210      # MTIME
 211      my $time = $param->valueOrDefault('Time', GZIP_MTIME_DEFAULT) ;
 212  
 213      # EXTRA FLAGS
 214      my $extra_flags = $param->valueOrDefault('ExtraFlags', GZIP_XFL_DEFAULT);
 215  
 216      # OS CODE
 217      my $os_code = $param->valueOrDefault('OS_Code', GZIP_OS_DEFAULT) ;
 218  
 219  
 220      my $out = pack("C4 V C C", 
 221              GZIP_ID1,   # ID1
 222              GZIP_ID2,   # ID2
 223              $method,    # Compression Method
 224              $flags,     # Flags
 225              $time,      # Modification Time
 226              $extra_flags, # Extra Flags
 227              $os_code,   # Operating System Code
 228              ) ;
 229  
 230      # EXTRA
 231      if ($flags & GZIP_FLG_FEXTRA) {
 232          my $extra = $param->value('ExtraField') ;
 233          $out .= pack("v", length $extra) . $extra ;
 234      }
 235  
 236      # NAME
 237      if ($flags & GZIP_FLG_FNAME) {
 238          my $name .= $param->value('Name') ;
 239          $name =~ s/\x00.*$//;
 240          $out .= $name ;
 241          # Terminate the filename with NULL unless it already is
 242          $out .= GZIP_NULL_BYTE 
 243              if !length $name or
 244                 substr($name, 1, -1) ne GZIP_NULL_BYTE ;
 245      }
 246  
 247      # COMMENT
 248      if ($flags & GZIP_FLG_FCOMMENT) {
 249          my $comment .= $param->value('Comment') ;
 250          $comment =~ s/\x00.*$//;
 251          $out .= $comment ;
 252          # Terminate the comment with NULL unless it already is
 253          $out .= GZIP_NULL_BYTE
 254              if ! length $comment or
 255                 substr($comment, 1, -1) ne GZIP_NULL_BYTE;
 256      }
 257  
 258      # HEADER CRC
 259      $out .= pack("v", crc32($out) & 0x00FF ) if $param->value('HeaderCRC') ;
 260  
 261      noUTF8($out);
 262  
 263      return $out ;
 264  }
 265  
 266  sub mkFinalTrailer
 267  {
 268      return '';
 269  }
 270  
 271  1; 
 272  
 273  __END__
 274  
 275  =head1 NAME
 276  
 277  
 278  
 279  IO::Compress::Gzip - Write RFC 1952 files/buffers
 280   
 281   
 282  
 283  =head1 SYNOPSIS
 284  
 285      use IO::Compress::Gzip qw(gzip $GzipError) ;
 286  
 287  
 288      my $status = gzip $input => $output [,OPTS] 
 289          or die "gzip failed: $GzipError\n";
 290  
 291      my $z = new IO::Compress::Gzip $output [,OPTS]
 292          or die "gzip failed: $GzipError\n";
 293  
 294      $z->print($string);
 295      $z->printf($format, $string);
 296      $z->write($string);
 297      $z->syswrite($string [, $length, $offset]);
 298      $z->flush();
 299      $z->tell();
 300      $z->eof();
 301      $z->seek($position, $whence);
 302      $z->binmode();
 303      $z->fileno();
 304      $z->opened();
 305      $z->autoflush();
 306      $z->input_line_number();
 307      $z->newStream( [OPTS] );
 308      
 309      $z->deflateParams();
 310      
 311      $z->close() ;
 312  
 313      $GzipError ;
 314  
 315      # IO::File mode
 316  
 317      print $z $string;
 318      printf $z $format, $string;
 319      tell $z
 320      eof $z
 321      seek $z, $position, $whence
 322      binmode $z
 323      fileno $z
 324      close $z ;
 325      
 326  
 327  =head1 DESCRIPTION
 328  
 329  
 330  This module provides a Perl interface that allows writing compressed
 331  data to files or buffer as defined in RFC 1952.
 332  
 333  
 334  
 335  
 336  
 337  All the gzip headers defined in RFC 1952 can be created using
 338  this module.
 339  
 340  
 341  
 342  
 343  
 344  
 345  
 346  For reading RFC 1952 files/buffers, see the companion module 
 347  L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip>.
 348  
 349  
 350  =head1 Functional Interface
 351  
 352  A top-level function, C<gzip>, is provided to carry out
 353  "one-shot" compression between buffers and/or files. For finer
 354  control over the compression process, see the L</"OO Interface">
 355  section.
 356  
 357      use IO::Compress::Gzip qw(gzip $GzipError) ;
 358  
 359      gzip $input => $output [,OPTS] 
 360          or die "gzip failed: $GzipError\n";
 361  
 362  
 363  
 364  The functional interface needs Perl5.005 or better.
 365  
 366  
 367  =head2 gzip $input => $output [, OPTS]
 368  
 369  
 370  C<gzip> expects at least two parameters, C<$input> and C<$output>.
 371  
 372  =head3 The C<$input> parameter
 373  
 374  The parameter, C<$input>, is used to define the source of
 375  the uncompressed data. 
 376  
 377  It can take one of the following forms:
 378  
 379  =over 5
 380  
 381  =item A filename
 382  
 383  If the C<$input> parameter is a simple scalar, it is assumed to be a
 384  filename. This file will be opened for reading and the input data
 385  will be read from it.
 386  
 387  =item A filehandle
 388  
 389  If the C<$input> parameter is a filehandle, the input data will be
 390  read from it.
 391  The string '-' can be used as an alias for standard input.
 392  
 393  =item A scalar reference 
 394  
 395  If C<$input> is a scalar reference, the input data will be read
 396  from C<$$input>.
 397  
 398  =item An array reference 
 399  
 400  If C<$input> is an array reference, each element in the array must be a
 401  filename.
 402  
 403  The input data will be read from each file in turn. 
 404  
 405  The complete array will be walked to ensure that it only
 406  contains valid filenames before any data is compressed.
 407  
 408  
 409  
 410  =item An Input FileGlob string
 411  
 412  If C<$input> is a string that is delimited by the characters "<" and ">"
 413  C<gzip> will assume that it is an I<input fileglob string>. The
 414  input is the list of files that match the fileglob.
 415  
 416  If the fileglob does not match any files ...
 417  
 418  See L<File::GlobMapper|File::GlobMapper> for more details.
 419  
 420  
 421  =back
 422  
 423  If the C<$input> parameter is any other type, C<undef> will be returned.
 424  
 425  
 426  In addition, if C<$input> is a simple filename, the default values for
 427  the C<Name> and C<Time> options will be sourced from that file.
 428  
 429  If you do not want to use these defaults they can be overridden by
 430  explicitly setting the C<Name> and C<Time> options or by setting the
 431  C<Minimal> parameter.
 432  
 433  
 434  
 435  =head3 The C<$output> parameter
 436  
 437  The parameter C<$output> is used to control the destination of the
 438  compressed data. This parameter can take one of these forms.
 439  
 440  =over 5
 441  
 442  =item A filename
 443  
 444  If the C<$output> parameter is a simple scalar, it is assumed to be a
 445  filename.  This file will be opened for writing and the compressed
 446  data will be written to it.
 447  
 448  =item A filehandle
 449  
 450  If the C<$output> parameter is a filehandle, the compressed data
 451  will be written to it.
 452  The string '-' can be used as an alias for standard output.
 453  
 454  
 455  =item A scalar reference 
 456  
 457  If C<$output> is a scalar reference, the compressed data will be
 458  stored in C<$$output>.
 459  
 460  
 461  
 462  =item An Array Reference
 463  
 464  If C<$output> is an array reference, the compressed data will be
 465  pushed onto the array.
 466  
 467  =item An Output FileGlob
 468  
 469  If C<$output> is a string that is delimited by the characters "<" and ">"
 470  C<gzip> will assume that it is an I<output fileglob string>. The
 471  output is the list of files that match the fileglob.
 472  
 473  When C<$output> is an fileglob string, C<$input> must also be a fileglob
 474  string. Anything else is an error.
 475  
 476  =back
 477  
 478  If the C<$output> parameter is any other type, C<undef> will be returned.
 479  
 480  
 481  
 482  =head2 Notes
 483  
 484  
 485  
 486  When C<$input> maps to multiple files/buffers and C<$output> is a single
 487  file/buffer the input files/buffers will be stored
 488  in C<$output> as a concatenated series of compressed data streams.
 489  
 490  
 491  
 492  
 493  
 494  
 495  =head2 Optional Parameters
 496  
 497  Unless specified below, the optional parameters for C<gzip>,
 498  C<OPTS>, are the same as those used with the OO interface defined in the
 499  L</"Constructor Options"> section below.
 500  
 501  =over 5
 502  
 503  =item C<< AutoClose => 0|1 >>
 504  
 505  This option applies to any input or output data streams to 
 506  C<gzip> that are filehandles.
 507  
 508  If C<AutoClose> is specified, and the value is true, it will result in all
 509  input and/or output filehandles being closed once C<gzip> has
 510  completed.
 511  
 512  This parameter defaults to 0.
 513  
 514  
 515  =item C<< BinModeIn => 0|1 >>
 516  
 517  When reading from a file or filehandle, set C<binmode> before reading.
 518  
 519  Defaults to 0.
 520  
 521  
 522  
 523  
 524  
 525  =item C<< Append => 0|1 >>
 526  
 527  TODO
 528  
 529  
 530  
 531  =back
 532  
 533  
 534  
 535  =head2 Examples
 536  
 537  To read the contents of the file C<file1.txt> and write the compressed
 538  data to the file C<file1.txt.gz>.
 539  
 540      use strict ;
 541      use warnings ;
 542      use IO::Compress::Gzip qw(gzip $GzipError) ;
 543  
 544      my $input = "file1.txt";
 545      gzip $input => "$input.gz"
 546          or die "gzip failed: $GzipError\n";
 547  
 548  
 549  To read from an existing Perl filehandle, C<$input>, and write the
 550  compressed data to a buffer, C<$buffer>.
 551  
 552      use strict ;
 553      use warnings ;
 554      use IO::Compress::Gzip qw(gzip $GzipError) ;
 555      use IO::File ;
 556  
 557      my $input = new IO::File "<file1.txt"
 558          or die "Cannot open 'file1.txt': $!\n" ;
 559      my $buffer ;
 560      gzip $input => \$buffer 
 561          or die "gzip failed: $GzipError\n";
 562  
 563  To compress all files in the directory "/my/home" that match "*.txt"
 564  and store the compressed data in the same directory
 565  
 566      use strict ;
 567      use warnings ;
 568      use IO::Compress::Gzip qw(gzip $GzipError) ;
 569  
 570      gzip '</my/home/*.txt>' => '<*.gz>'
 571          or die "gzip failed: $GzipError\n";
 572  
 573  and if you want to compress each file one at a time, this will do the trick
 574  
 575      use strict ;
 576      use warnings ;
 577      use IO::Compress::Gzip qw(gzip $GzipError) ;
 578  
 579      for my $input ( glob "/my/home/*.txt" )
 580      {
 581          my $output = "$input.gz" ;
 582          gzip $input => $output 
 583              or die "Error compressing '$input': $GzipError\n";
 584      }
 585  
 586  
 587  =head1 OO Interface
 588  
 589  =head2 Constructor
 590  
 591  The format of the constructor for C<IO::Compress::Gzip> is shown below
 592  
 593      my $z = new IO::Compress::Gzip $output [,OPTS]
 594          or die "IO::Compress::Gzip failed: $GzipError\n";
 595  
 596  It returns an C<IO::Compress::Gzip> object on success and undef on failure. 
 597  The variable C<$GzipError> will contain an error message on failure.
 598  
 599  If you are running Perl 5.005 or better the object, C<$z>, returned from 
 600  IO::Compress::Gzip can be used exactly like an L<IO::File|IO::File> filehandle. 
 601  This means that all normal output file operations can be carried out 
 602  with C<$z>. 
 603  For example, to write to a compressed file/buffer you can use either of 
 604  these forms
 605  
 606      $z->print("hello world\n");
 607      print $z "hello world\n";
 608  
 609  The mandatory parameter C<$output> is used to control the destination
 610  of the compressed data. This parameter can take one of these forms.
 611  
 612  =over 5
 613  
 614  =item A filename
 615  
 616  If the C<$output> parameter is a simple scalar, it is assumed to be a
 617  filename. This file will be opened for writing and the compressed data
 618  will be written to it.
 619  
 620  =item A filehandle
 621  
 622  If the C<$output> parameter is a filehandle, the compressed data will be
 623  written to it.
 624  The string '-' can be used as an alias for standard output.
 625  
 626  
 627  =item A scalar reference 
 628  
 629  If C<$output> is a scalar reference, the compressed data will be stored
 630  in C<$$output>.
 631  
 632  =back
 633  
 634  If the C<$output> parameter is any other type, C<IO::Compress::Gzip>::new will
 635  return undef.
 636  
 637  =head2 Constructor Options
 638  
 639  C<OPTS> is any combination of the following options:
 640  
 641  =over 5
 642  
 643  =item C<< AutoClose => 0|1 >>
 644  
 645  This option is only valid when the C<$output> parameter is a filehandle. If
 646  specified, and the value is true, it will result in the C<$output> being
 647  closed once either the C<close> method is called or the C<IO::Compress::Gzip>
 648  object is destroyed.
 649  
 650  This parameter defaults to 0.
 651  
 652  =item C<< Append => 0|1 >>
 653  
 654  Opens C<$output> in append mode. 
 655  
 656  The behaviour of this option is dependent on the type of C<$output>.
 657  
 658  =over 5
 659  
 660  =item * A Buffer
 661  
 662  If C<$output> is a buffer and C<Append> is enabled, all compressed data
 663  will be append to the end if C<$output>. Otherwise C<$output> will be
 664  cleared before any data is written to it.
 665  
 666  =item * A Filename
 667  
 668  If C<$output> is a filename and C<Append> is enabled, the file will be
 669  opened in append mode. Otherwise the contents of the file, if any, will be
 670  truncated before any compressed data is written to it.
 671  
 672  =item * A Filehandle
 673  
 674  If C<$output> is a filehandle, the file pointer will be positioned to the
 675  end of the file via a call to C<seek> before any compressed data is written
 676  to it.  Otherwise the file pointer will not be moved.
 677  
 678  =back
 679  
 680  This parameter defaults to 0.
 681  
 682  
 683  
 684  
 685  
 686  =item C<< Merge => 0|1 >>
 687  
 688  This option is used to compress input data and append it to an existing
 689  compressed data stream in C<$output>. The end result is a single compressed
 690  data stream stored in C<$output>. 
 691  
 692  
 693  
 694  It is a fatal error to attempt to use this option when C<$output> is not an
 695  RFC 1952 data stream.
 696  
 697  
 698  
 699  There are a number of other limitations with the C<Merge> option:
 700  
 701  =over 5 
 702  
 703  =item 1
 704  
 705  This module needs to have been built with zlib 1.2.1 or better to work. A
 706  fatal error will be thrown if C<Merge> is used with an older version of
 707  zlib.  
 708  
 709  =item 2
 710  
 711  If C<$output> is a file or a filehandle, it must be seekable.
 712  
 713  =back
 714  
 715  
 716  This parameter defaults to 0.
 717  
 718  
 719  
 720  =item -Level 
 721  
 722  Defines the compression level used by zlib. The value should either be
 723  a number between 0 and 9 (0 means no compression and 9 is maximum
 724  compression), or one of the symbolic constants defined below.
 725  
 726     Z_NO_COMPRESSION
 727     Z_BEST_SPEED
 728     Z_BEST_COMPRESSION
 729     Z_DEFAULT_COMPRESSION
 730  
 731  The default is Z_DEFAULT_COMPRESSION.
 732  
 733  Note, these constants are not imported by C<IO::Compress::Gzip> by default.
 734  
 735      use IO::Compress::Gzip qw(:strategy);
 736      use IO::Compress::Gzip qw(:constants);
 737      use IO::Compress::Gzip qw(:all);
 738  
 739  =item -Strategy 
 740  
 741  Defines the strategy used to tune the compression. Use one of the symbolic
 742  constants defined below.
 743  
 744     Z_FILTERED
 745     Z_HUFFMAN_ONLY
 746     Z_RLE
 747     Z_FIXED
 748     Z_DEFAULT_STRATEGY
 749  
 750  The default is Z_DEFAULT_STRATEGY.
 751  
 752  
 753  
 754  
 755  
 756  
 757  =item C<< Minimal => 0|1 >>
 758  
 759  If specified, this option will force the creation of the smallest possible
 760  compliant gzip header (which is exactly 10 bytes long) as defined in
 761  RFC 1952.
 762  
 763  See the section titled "Compliance" in RFC 1952 for a definition 
 764  of the values used for the fields in the gzip header.
 765  
 766  All other parameters that control the content of the gzip header will
 767  be ignored if this parameter is set to 1.
 768  
 769  This parameter defaults to 0.
 770  
 771  =item C<< Comment => $comment >>
 772  
 773  Stores the contents of C<$comment> in the COMMENT field in
 774  the gzip header.
 775  By default, no comment field is written to the gzip file.
 776  
 777  If the C<-Strict> option is enabled, the comment can only consist of ISO
 778  8859-1 characters plus line feed.
 779  
 780  If the C<-Strict> option is disabled, the comment field can contain any
 781  character except NULL. If any null characters are present, the field
 782  will be truncated at the first NULL.
 783  
 784  =item C<< Name => $string >>
 785  
 786  Stores the contents of C<$string> in the gzip NAME header field. If
 787  C<Name> is not specified, no gzip NAME field will be created.
 788  
 789  If the C<-Strict> option is enabled, C<$string> can only consist of ISO
 790  8859-1 characters.
 791  
 792  If C<-Strict> is disabled, then C<$string> can contain any character
 793  except NULL. If any null characters are present, the field will be
 794  truncated at the first NULL.
 795  
 796  =item C<< Time => $number >>
 797  
 798  Sets the MTIME field in the gzip header to $number.
 799  
 800  This field defaults to the time the C<IO::Compress::Gzip> object was created
 801  if this option is not specified.
 802  
 803  =item C<< TextFlag => 0|1 >>
 804  
 805  This parameter controls the setting of the FLG.FTEXT bit in the gzip
 806  header. It is used to signal that the data stored in the gzip file/buffer
 807  is probably text.
 808  
 809  The default is 0. 
 810  
 811  =item C<< HeaderCRC => 0|1 >>
 812  
 813  When true this parameter will set the FLG.FHCRC bit to 1 in the gzip header
 814  and set the CRC16 header field to the CRC of the complete gzip header
 815  except the CRC16 field itself.
 816  
 817  B<Note> that gzip files created with the C<HeaderCRC> flag set to 1 cannot
 818  be read by most, if not all, of the the standard gunzip utilities, most
 819  notably gzip version 1.2.4. You should therefore avoid using this option if
 820  you want to maximize the portability of your gzip files.
 821  
 822  This parameter defaults to 0.
 823  
 824  =item C<< OS_Code => $value >>
 825  
 826  Stores C<$value> in the gzip OS header field. A number between 0 and 255 is
 827  valid.
 828  
 829  If not specified, this parameter defaults to the OS code of the Operating
 830  System this module was built on. The value 3 is used as a catch-all for all
 831  Unix variants and unknown Operating Systems.
 832  
 833  =item C<< ExtraField => $data >>
 834  
 835  This parameter allows additional metadata to be stored in the ExtraField in
 836  the gzip header. An RFC 1952 compliant ExtraField consists of zero or more
 837  subfields. Each subfield consists of a two byte header followed by the
 838  subfield data.
 839  
 840  The list of subfields can be supplied in any of the following formats
 841  
 842      -ExtraField => [$id1, $data1,
 843                      $id2, $data2,
 844                       ...
 845                     ]
 846      -ExtraField => [ [$id1 => $data1],
 847                       [$id2 => $data2],
 848                       ...
 849                     ]
 850      -ExtraField => { $id1 => $data1,
 851                       $id2 => $data2,
 852                       ...
 853                     }
 854  
 855  Where C<$id1>, C<$id2> are two byte subfield ID's. The second byte of
 856  the ID cannot be 0, unless the C<Strict> option has been disabled.
 857  
 858  If you use the hash syntax, you have no control over the order in which
 859  the ExtraSubFields are stored, plus you cannot have SubFields with
 860  duplicate ID.
 861  
 862  Alternatively the list of subfields can by supplied as a scalar, thus
 863  
 864      -ExtraField => $rawdata
 865  
 866  If you use the raw format, and the C<Strict> option is enabled,
 867  C<IO::Compress::Gzip> will check that C<$rawdata> consists of zero or more
 868  conformant sub-fields. When C<Strict> is disabled, C<$rawdata> can
 869  consist of any arbitrary byte stream.
 870  
 871  The maximum size of the Extra Field 65535 bytes.
 872  
 873  =item C<< ExtraFlags => $value >>
 874  
 875  Sets the XFL byte in the gzip header to C<$value>.
 876  
 877  If this option is not present, the value stored in XFL field will be
 878  determined by the setting of the C<Level> option.
 879  
 880  If C<< Level => Z_BEST_SPEED >> has been specified then XFL is set to 2.
 881  If C<< Level => Z_BEST_COMPRESSION >> has been specified then XFL is set to 4.
 882  Otherwise XFL is set to 0.
 883  
 884  
 885  
 886  =item C<< Strict => 0|1 >>
 887  
 888  
 889  
 890  C<Strict> will optionally police the values supplied with other options
 891  to ensure they are compliant with RFC1952.
 892  
 893  This option is enabled by default.
 894  
 895  If C<Strict> is enabled the following behaviour will be policed:
 896  
 897  =over 5
 898  
 899  =item * 
 900  
 901  The value supplied with the C<Name> option can only contain ISO 8859-1
 902  characters.
 903  
 904  =item * 
 905  
 906  The value supplied with the C<Comment> option can only contain ISO 8859-1
 907  characters plus line-feed.
 908  
 909  =item *
 910  
 911  The values supplied with the C<-Name> and C<-Comment> options cannot
 912  contain multiple embedded nulls.
 913  
 914  =item * 
 915  
 916  If an C<ExtraField> option is specified and it is a simple scalar,
 917  it must conform to the sub-field structure as defined in RFC 1952.
 918  
 919  =item * 
 920  
 921  If an C<ExtraField> option is specified the second byte of the ID will be
 922  checked in each subfield to ensure that it does not contain the reserved
 923  value 0x00.
 924  
 925  =back
 926  
 927  When C<Strict> is disabled the following behaviour will be policed:
 928  
 929  =over 5
 930  
 931  =item * 
 932  
 933  The value supplied with C<-Name> option can contain
 934  any character except NULL.
 935  
 936  =item * 
 937  
 938  The value supplied with C<-Comment> option can contain any character
 939  except NULL.
 940  
 941  =item *
 942  
 943  The values supplied with the C<-Name> and C<-Comment> options can contain
 944  multiple embedded nulls. The string written to the gzip header will
 945  consist of the characters up to, but not including, the first embedded
 946  NULL.
 947  
 948  =item * 
 949  
 950  If an C<ExtraField> option is specified and it is a simple scalar, the
 951  structure will not be checked. The only error is if the length is too big.
 952  
 953  =item * 
 954  
 955  The ID header in an C<ExtraField> sub-field can consist of any two bytes.
 956  
 957  =back
 958  
 959  
 960  
 961  =back
 962  
 963  =head2 Examples
 964  
 965  TODO
 966  
 967  =head1 Methods 
 968  
 969  =head2 print
 970  
 971  Usage is
 972  
 973      $z->print($data)
 974      print $z $data
 975  
 976  Compresses and outputs the contents of the C<$data> parameter. This
 977  has the same behaviour as the C<print> built-in.
 978  
 979  Returns true if successful.
 980  
 981  =head2 printf
 982  
 983  Usage is
 984  
 985      $z->printf($format, $data)
 986      printf $z $format, $data
 987  
 988  Compresses and outputs the contents of the C<$data> parameter.
 989  
 990  Returns true if successful.
 991  
 992  =head2 syswrite
 993  
 994  Usage is
 995  
 996      $z->syswrite $data
 997      $z->syswrite $data, $length
 998      $z->syswrite $data, $length, $offset
 999  
1000  Compresses and outputs the contents of the C<$data> parameter.
1001  
1002  Returns the number of uncompressed bytes written, or C<undef> if
1003  unsuccessful.
1004  
1005  =head2 write
1006  
1007  Usage is
1008  
1009      $z->write $data
1010      $z->write $data, $length
1011      $z->write $data, $length, $offset
1012  
1013  Compresses and outputs the contents of the C<$data> parameter.
1014  
1015  Returns the number of uncompressed bytes written, or C<undef> if
1016  unsuccessful.
1017  
1018  =head2 flush
1019  
1020  Usage is
1021  
1022  
1023      $z->flush;
1024      $z->flush($flush_type);
1025  
1026  
1027  Flushes any pending compressed data to the output file/buffer.
1028  
1029  
1030  This method takes an optional parameter, C<$flush_type>, that controls
1031  how the flushing will be carried out. By default the C<$flush_type>
1032  used is C<Z_FINISH>. Other valid values for C<$flush_type> are
1033  C<Z_NO_FLUSH>, C<Z_SYNC_FLUSH>, C<Z_FULL_FLUSH> and C<Z_BLOCK>. It is
1034  strongly recommended that you only set the C<flush_type> parameter if
1035  you fully understand the implications of what it does - overuse of C<flush>
1036  can seriously degrade the level of compression achieved. See the C<zlib>
1037  documentation for details.
1038  
1039  
1040  Returns true on success.
1041  
1042  
1043  =head2 tell
1044  
1045  Usage is
1046  
1047      $z->tell()
1048      tell $z
1049  
1050  Returns the uncompressed file offset.
1051  
1052  =head2 eof
1053  
1054  Usage is
1055  
1056      $z->eof();
1057      eof($z);
1058  
1059  
1060  
1061  Returns true if the C<close> method has been called.
1062  
1063  
1064  
1065  =head2 seek
1066  
1067      $z->seek($position, $whence);
1068      seek($z, $position, $whence);
1069  
1070  
1071  
1072  
1073  Provides a sub-set of the C<seek> functionality, with the restriction
1074  that it is only legal to seek forward in the output file/buffer.
1075  It is a fatal error to attempt to seek backward.
1076  
1077  Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
1078  
1079  
1080  
1081  The C<$whence> parameter takes one the usual values, namely SEEK_SET,
1082  SEEK_CUR or SEEK_END.
1083  
1084  Returns 1 on success, 0 on failure.
1085  
1086  =head2 binmode
1087  
1088  Usage is
1089  
1090      $z->binmode
1091      binmode $z ;
1092  
1093  This is a noop provided for completeness.
1094  
1095  =head2 opened
1096  
1097      $z->opened()
1098  
1099  Returns true if the object currently refers to a opened file/buffer. 
1100  
1101  =head2 autoflush
1102  
1103      my $prev = $z->autoflush()
1104      my $prev = $z->autoflush(EXPR)
1105  
1106  If the C<$z> object is associated with a file or a filehandle, this method
1107  returns the current autoflush setting for the underlying filehandle. If
1108  C<EXPR> is present, and is non-zero, it will enable flushing after every
1109  write/print operation.
1110  
1111  If C<$z> is associated with a buffer, this method has no effect and always
1112  returns C<undef>.
1113  
1114  B<Note> that the special variable C<$|> B<cannot> be used to set or
1115  retrieve the autoflush setting.
1116  
1117  =head2 input_line_number
1118  
1119      $z->input_line_number()
1120      $z->input_line_number(EXPR)
1121  
1122  
1123  This method always returns C<undef> when compressing. 
1124  
1125  
1126  
1127  =head2 fileno
1128  
1129      $z->fileno()
1130      fileno($z)
1131  
1132  If the C<$z> object is associated with a file or a filehandle, this method
1133  will return the underlying file descriptor.
1134  
1135  If the C<$z> object is is associated with a buffer, this method will
1136  return undef.
1137  
1138  =head2 close
1139  
1140      $z->close() ;
1141      close $z ;
1142  
1143  
1144  
1145  Flushes any pending compressed data and then closes the output file/buffer. 
1146  
1147  
1148  
1149  For most versions of Perl this method will be automatically invoked if
1150  the IO::Compress::Gzip object is destroyed (either explicitly or by the
1151  variable with the reference to the object going out of scope). The
1152  exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
1153  these cases, the C<close> method will be called automatically, but
1154  not until global destruction of all live objects when the program is
1155  terminating.
1156  
1157  Therefore, if you want your scripts to be able to run on all versions
1158  of Perl, you should call C<close> explicitly and not rely on automatic
1159  closing.
1160  
1161  Returns true on success, otherwise 0.
1162  
1163  If the C<AutoClose> option has been enabled when the IO::Compress::Gzip
1164  object was created, and the object is associated with a file, the
1165  underlying file will also be closed.
1166  
1167  
1168  
1169  
1170  =head2 newStream([OPTS])
1171  
1172  Usage is
1173  
1174      $z->newStream( [OPTS] )
1175  
1176  Closes the current compressed data stream and starts a new one.
1177  
1178  OPTS consists of any of the the options that are available when creating
1179  the C<$z> object.
1180  
1181  See the L</"Constructor Options"> section for more details.
1182  
1183  
1184  =head2 deflateParams
1185  
1186  Usage is
1187  
1188      $z->deflateParams
1189  
1190  TODO
1191  
1192  
1193  =head1 Importing 
1194  
1195  
1196  A number of symbolic constants are required by some methods in 
1197  C<IO::Compress::Gzip>. None are imported by default.
1198  
1199  
1200  
1201  =over 5
1202  
1203  =item :all
1204  
1205  
1206  Imports C<gzip>, C<$GzipError> and all symbolic
1207  constants that can be used by C<IO::Compress::Gzip>. Same as doing this
1208  
1209      use IO::Compress::Gzip qw(gzip $GzipError :constants) ;
1210  
1211  =item :constants
1212  
1213  Import all symbolic constants. Same as doing this
1214  
1215  
1216      use IO::Compress::Gzip qw(:flush :level :strategy) ;
1217  
1218  
1219  =item :flush
1220  
1221  These symbolic constants are used by the C<flush> method.
1222  
1223      Z_NO_FLUSH
1224      Z_PARTIAL_FLUSH
1225      Z_SYNC_FLUSH
1226      Z_FULL_FLUSH
1227      Z_FINISH
1228      Z_BLOCK
1229  
1230  =item :level
1231  
1232  These symbolic constants are used by the C<Level> option in the constructor.
1233  
1234      Z_NO_COMPRESSION
1235      Z_BEST_SPEED
1236      Z_BEST_COMPRESSION
1237      Z_DEFAULT_COMPRESSION
1238  
1239  
1240  =item :strategy
1241  
1242  These symbolic constants are used by the C<Strategy> option in the constructor.
1243  
1244      Z_FILTERED
1245      Z_HUFFMAN_ONLY
1246      Z_RLE
1247      Z_FIXED
1248      Z_DEFAULT_STRATEGY
1249  
1250      
1251      
1252  
1253  =back
1254  
1255  For 
1256  
1257  =head1 EXAMPLES
1258  
1259  TODO
1260  
1261  
1262  
1263  
1264  
1265  
1266  
1267  
1268  
1269  
1270  
1271  =head1 SEE ALSO
1272  
1273  L<Compress::Zlib>, 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>, L<IO::Uncompress::AnyUncompress>
1274  
1275  L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1276  
1277  L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1278  L<Archive::Tar|Archive::Tar>,
1279  L<IO::Zlib|IO::Zlib>
1280  
1281  
1282  For RFC 1950, 1951 and 1952 see 
1283  F<http://www.faqs.org/rfcs/rfc1950.html>,
1284  F<http://www.faqs.org/rfcs/rfc1951.html> and
1285  F<http://www.faqs.org/rfcs/rfc1952.html>
1286  
1287  The I<zlib> compression library was written by Jean-loup Gailly
1288  F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1289  
1290  The primary site for the I<zlib> compression library is
1291  F<http://www.zlib.org>.
1292  
1293  The primary site for gzip is F<http://www.gzip.org>.
1294  
1295  
1296  
1297  
1298  =head1 AUTHOR
1299  
1300  This module was written by Paul Marquess, F<pmqs@cpan.org>. 
1301  
1302  
1303  
1304  =head1 MODIFICATION HISTORY
1305  
1306  See the Changes file.
1307  
1308  =head1 COPYRIGHT AND LICENSE
1309  
1310  Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
1311  
1312  This program is free software; you can redistribute it and/or
1313  modify it under the same terms as Perl itself.
1314  
1315