"Fossies" - the Fresh Open Source Software Archive

Member "IO-Compress-2.093/lib/IO/Compress/Gzip.pm" (7 Dec 2019, 35185 Bytes) of package /linux/privat/IO-Compress-2.093.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) Perl source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "Gzip.pm" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report: 2.092_vs_2.093.

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