01ee34ef15cee32c943e963d3665fcf2e982f173
[perl.git] / cpan / IO-Compress / lib / IO / Compress / Gzip.pm
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.068 () ; 
12 use IO::Compress::Adapter::Deflate 2.068 ;
13
14 use IO::Compress::Base::Common  2.068 qw(:Status );
15 use IO::Compress::Gzip::Constants 2.068 ;
16 use IO::Compress::Zlib::Extra 2.068 ;
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.068';
29 $GzipError = '' ;
30
31 @ISA    = qw(Exporter IO::Compress::RawDeflate);
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  
282
283 =head1 SYNOPSIS
284
285     use IO::Compress::Gzip qw(gzip $GzipError) ;
286
287     my $status = gzip $input => $output [,OPTS] 
288         or die "gzip failed: $GzipError\n";
289
290     my $z = new IO::Compress::Gzip $output [,OPTS]
291         or die "gzip failed: $GzipError\n";
292
293     $z->print($string);
294     $z->printf($format, $string);
295     $z->write($string);
296     $z->syswrite($string [, $length, $offset]);
297     $z->flush();
298     $z->tell();
299     $z->eof();
300     $z->seek($position, $whence);
301     $z->binmode();
302     $z->fileno();
303     $z->opened();
304     $z->autoflush();
305     $z->input_line_number();
306     $z->newStream( [OPTS] );
307     
308     $z->deflateParams();
309     
310     $z->close() ;
311
312     $GzipError ;
313
314     # IO::File mode
315
316     print $z $string;
317     printf $z $format, $string;
318     tell $z
319     eof $z
320     seek $z, $position, $whence
321     binmode $z
322     fileno $z
323     close $z ;
324     
325
326 =head1 DESCRIPTION
327
328 This module provides a Perl interface that allows writing compressed
329 data to files or buffer as defined in RFC 1952.
330
331 All the gzip headers defined in RFC 1952 can be created using
332 this module.
333
334 For reading RFC 1952 files/buffers, see the companion module 
335 L<IO::Uncompress::Gunzip|IO::Uncompress::Gunzip>.
336
337 =head1 Functional Interface
338
339 A top-level function, C<gzip>, is provided to carry out
340 "one-shot" compression between buffers and/or files. For finer
341 control over the compression process, see the L</"OO Interface">
342 section.
343
344     use IO::Compress::Gzip qw(gzip $GzipError) ;
345
346     gzip $input_filename_or_reference => $output_filename_or_reference [,OPTS] 
347         or die "gzip failed: $GzipError\n";
348
349 The functional interface needs Perl5.005 or better.
350
351 =head2 gzip $input_filename_or_reference => $output_filename_or_reference [, OPTS]
352
353 C<gzip> expects at least two parameters,
354 C<$input_filename_or_reference> and C<$output_filename_or_reference>.
355
356 =head3 The C<$input_filename_or_reference> parameter
357
358 The parameter, C<$input_filename_or_reference>, is used to define the
359 source of the uncompressed data. 
360
361 It can take one of the following forms:
362
363 =over 5
364
365 =item A filename
366
367 If the <$input_filename_or_reference> parameter is a simple scalar, it is
368 assumed to be a filename. This file will be opened for reading and the
369 input data will be read from it.
370
371 =item A filehandle
372
373 If the C<$input_filename_or_reference> parameter is a filehandle, the input
374 data will be read from it.  The string '-' can be used as an alias for
375 standard input.
376
377 =item A scalar reference 
378
379 If C<$input_filename_or_reference> is a scalar reference, the input data
380 will be read from C<$$input_filename_or_reference>.
381
382 =item An array reference 
383
384 If C<$input_filename_or_reference> is an array reference, each element in
385 the array must be a filename.
386
387 The input data will be read from each file in turn. 
388
389 The complete array will be walked to ensure that it only
390 contains valid filenames before any data is compressed.
391
392 =item An Input FileGlob string
393
394 If C<$input_filename_or_reference> is a string that is delimited by the
395 characters "<" and ">" C<gzip> will assume that it is an 
396 I<input fileglob string>. The input is the list of files that match the 
397 fileglob.
398
399 See L<File::GlobMapper|File::GlobMapper> for more details.
400
401 =back
402
403 If the C<$input_filename_or_reference> parameter is any other type,
404 C<undef> will be returned.
405
406 In addition, if C<$input_filename_or_reference> is a simple filename, 
407 the default values for
408 the C<Name> and C<Time> options will be sourced from that file.
409
410 If you do not want to use these defaults they can be overridden by
411 explicitly setting the C<Name> and C<Time> options or by setting the
412 C<Minimal> parameter.
413
414 =head3 The C<$output_filename_or_reference> parameter
415
416 The parameter C<$output_filename_or_reference> is used to control the
417 destination of the compressed data. This parameter can take one of
418 these forms.
419
420 =over 5
421
422 =item A filename
423
424 If the C<$output_filename_or_reference> parameter is a simple scalar, it is
425 assumed to be a filename.  This file will be opened for writing and the 
426 compressed data will be written to it.
427
428 =item A filehandle
429
430 If the C<$output_filename_or_reference> parameter is a filehandle, the
431 compressed data will be written to it.  The string '-' can be used as
432 an alias for standard output.
433
434 =item A scalar reference 
435
436 If C<$output_filename_or_reference> is a scalar reference, the
437 compressed data will be stored in C<$$output_filename_or_reference>.
438
439 =item An Array Reference
440
441 If C<$output_filename_or_reference> is an array reference, 
442 the compressed data will be pushed onto the array.
443
444 =item An Output FileGlob
445
446 If C<$output_filename_or_reference> is a string that is delimited by the
447 characters "<" and ">" C<gzip> will assume that it is an
448 I<output fileglob string>. The output is the list of files that match the
449 fileglob.
450
451 When C<$output_filename_or_reference> is an fileglob string,
452 C<$input_filename_or_reference> must also be a fileglob string. Anything
453 else is an error.
454
455 See L<File::GlobMapper|File::GlobMapper> for more details.
456
457 =back
458
459 If the C<$output_filename_or_reference> parameter is any other type,
460 C<undef> will be returned.
461
462 =head2 Notes
463
464 When C<$input_filename_or_reference> maps to multiple files/buffers and
465 C<$output_filename_or_reference> is a single
466 file/buffer the input files/buffers will be stored
467 in C<$output_filename_or_reference> as a concatenated series of compressed data streams.
468
469 =head2 Optional Parameters
470
471 Unless specified below, the optional parameters for C<gzip>,
472 C<OPTS>, are the same as those used with the OO interface defined in the
473 L</"Constructor Options"> section below.
474
475 =over 5
476
477 =item C<< AutoClose => 0|1 >>
478
479 This option applies to any input or output data streams to 
480 C<gzip> that are filehandles.
481
482 If C<AutoClose> is specified, and the value is true, it will result in all
483 input and/or output filehandles being closed once C<gzip> has
484 completed.
485
486 This parameter defaults to 0.
487
488 =item C<< BinModeIn => 0|1 >>
489
490 When reading from a file or filehandle, set C<binmode> before reading.
491
492 Defaults to 0.
493
494 =item C<< Append => 0|1 >>
495
496 The behaviour of this option is dependent on the type of output data
497 stream.
498
499 =over 5
500
501 =item * A Buffer
502
503 If C<Append> is enabled, all compressed data will be append to the end of
504 the output buffer. Otherwise the output buffer will be cleared before any
505 compressed data is written to it.
506
507 =item * A Filename
508
509 If C<Append> is enabled, the file will be opened in append mode. Otherwise
510 the contents of the file, if any, will be truncated before any compressed
511 data is written to it.
512
513 =item * A Filehandle
514
515 If C<Append> is enabled, the filehandle will be positioned to the end of
516 the file via a call to C<seek> before any compressed data is
517 written to it.  Otherwise the file pointer will not be moved.
518
519 =back
520
521 When C<Append> is specified, and set to true, it will I<append> all compressed 
522 data to the output data stream.
523
524 So when the output is a filehandle it will carry out a seek to the eof
525 before writing any compressed data. If the output is a filename, it will be opened for
526 appending. If the output is a buffer, all compressed data will be
527 appended to the existing buffer.
528
529 Conversely when C<Append> is not specified, or it is present and is set to
530 false, it will operate as follows.
531
532 When the output is a filename, it will truncate the contents of the file
533 before writing any compressed data. If the output is a filehandle
534 its position will not be changed. If the output is a buffer, it will be
535 wiped before any compressed data is output.
536
537 Defaults to 0.
538
539 =back
540
541 =head2 Examples
542
543 To read the contents of the file C<file1.txt> and write the compressed
544 data to the file C<file1.txt.gz>.
545
546     use strict ;
547     use warnings ;
548     use IO::Compress::Gzip qw(gzip $GzipError) ;
549
550     my $input = "file1.txt";
551     gzip $input => "$input.gz"
552         or die "gzip failed: $GzipError\n";
553
554 To read from an existing Perl filehandle, C<$input>, and write the
555 compressed data to a buffer, C<$buffer>.
556
557     use strict ;
558     use warnings ;
559     use IO::Compress::Gzip qw(gzip $GzipError) ;
560     use IO::File ;
561
562     my $input = new IO::File "<file1.txt"
563         or die "Cannot open 'file1.txt': $!\n" ;
564     my $buffer ;
565     gzip $input => \$buffer 
566         or die "gzip failed: $GzipError\n";
567
568 To compress all files in the directory "/my/home" that match "*.txt"
569 and store the compressed data in the same directory
570
571     use strict ;
572     use warnings ;
573     use IO::Compress::Gzip qw(gzip $GzipError) ;
574
575     gzip '</my/home/*.txt>' => '<*.gz>'
576         or die "gzip failed: $GzipError\n";
577
578 and if you want to compress each file one at a time, this will do the trick
579
580     use strict ;
581     use warnings ;
582     use IO::Compress::Gzip qw(gzip $GzipError) ;
583
584     for my $input ( glob "/my/home/*.txt" )
585     {
586         my $output = "$input.gz" ;
587         gzip $input => $output 
588             or die "Error compressing '$input': $GzipError\n";
589     }
590
591 =head1 OO Interface
592
593 =head2 Constructor
594
595 The format of the constructor for C<IO::Compress::Gzip> is shown below
596
597     my $z = new IO::Compress::Gzip $output [,OPTS]
598         or die "IO::Compress::Gzip failed: $GzipError\n";
599
600 It returns an C<IO::Compress::Gzip> object on success and undef on failure. 
601 The variable C<$GzipError> will contain an error message on failure.
602
603 If you are running Perl 5.005 or better the object, C<$z>, returned from 
604 IO::Compress::Gzip can be used exactly like an L<IO::File|IO::File> filehandle. 
605 This means that all normal output file operations can be carried out 
606 with C<$z>. 
607 For example, to write to a compressed file/buffer you can use either of 
608 these forms
609
610     $z->print("hello world\n");
611     print $z "hello world\n";
612
613 The mandatory parameter C<$output> is used to control the destination
614 of the compressed data. This parameter can take one of these forms.
615
616 =over 5
617
618 =item A filename
619
620 If the C<$output> parameter is a simple scalar, it is assumed to be a
621 filename. This file will be opened for writing and the compressed data
622 will be written to it.
623
624 =item A filehandle
625
626 If the C<$output> parameter is a filehandle, the compressed data will be
627 written to it.
628 The string '-' can be used as an alias for standard output.
629
630 =item A scalar reference 
631
632 If C<$output> is a scalar reference, the compressed data will be stored
633 in C<$$output>.
634
635 =back
636
637 If the C<$output> parameter is any other type, C<IO::Compress::Gzip>::new will
638 return undef.
639
640 =head2 Constructor Options
641
642 C<OPTS> is any combination of the following options:
643
644 =over 5
645
646 =item C<< AutoClose => 0|1 >>
647
648 This option is only valid when the C<$output> parameter is a filehandle. If
649 specified, and the value is true, it will result in the C<$output> being
650 closed once either the C<close> method is called or the C<IO::Compress::Gzip>
651 object is destroyed.
652
653 This parameter defaults to 0.
654
655 =item C<< Append => 0|1 >>
656
657 Opens C<$output> in append mode. 
658
659 The behaviour of this option is dependent on the type of C<$output>.
660
661 =over 5
662
663 =item * A Buffer
664
665 If C<$output> is a buffer and C<Append> is enabled, all compressed data
666 will be append to the end of C<$output>. Otherwise C<$output> will be
667 cleared before any data is written to it.
668
669 =item * A Filename
670
671 If C<$output> is a filename and C<Append> is enabled, the file will be
672 opened in append mode. Otherwise the contents of the file, if any, will be
673 truncated before any compressed data is written to it.
674
675 =item * A Filehandle
676
677 If C<$output> is a filehandle, the file pointer will be positioned to the
678 end of the file via a call to C<seek> before any compressed data is written
679 to it.  Otherwise the file pointer will not be moved.
680
681 =back
682
683 This parameter defaults to 0.
684
685 =item C<< Merge => 0|1 >>
686
687 This option is used to compress input data and append it to an existing
688 compressed data stream in C<$output>. The end result is a single compressed
689 data stream stored in C<$output>. 
690
691 It is a fatal error to attempt to use this option when C<$output> is not an
692 RFC 1952 data stream.
693
694 There are a number of other limitations with the C<Merge> option:
695
696 =over 5 
697
698 =item 1
699
700 This module needs to have been built with zlib 1.2.1 or better to work. A
701 fatal error will be thrown if C<Merge> is used with an older version of
702 zlib.  
703
704 =item 2
705
706 If C<$output> is a file or a filehandle, it must be seekable.
707
708 =back
709
710 This parameter defaults to 0.
711
712 =item -Level 
713
714 Defines the compression level used by zlib. The value should either be
715 a number between 0 and 9 (0 means no compression and 9 is maximum
716 compression), or one of the symbolic constants defined below.
717
718    Z_NO_COMPRESSION
719    Z_BEST_SPEED
720    Z_BEST_COMPRESSION
721    Z_DEFAULT_COMPRESSION
722
723 The default is Z_DEFAULT_COMPRESSION.
724
725 Note, these constants are not imported by C<IO::Compress::Gzip> by default.
726
727     use IO::Compress::Gzip qw(:strategy);
728     use IO::Compress::Gzip qw(:constants);
729     use IO::Compress::Gzip qw(:all);
730
731 =item -Strategy 
732
733 Defines the strategy used to tune the compression. Use one of the symbolic
734 constants defined below.
735
736    Z_FILTERED
737    Z_HUFFMAN_ONLY
738    Z_RLE
739    Z_FIXED
740    Z_DEFAULT_STRATEGY
741
742 The default is Z_DEFAULT_STRATEGY.
743
744 =item C<< Minimal => 0|1 >>
745
746 If specified, this option will force the creation of the smallest possible
747 compliant gzip header (which is exactly 10 bytes long) as defined in
748 RFC 1952.
749
750 See the section titled "Compliance" in RFC 1952 for a definition 
751 of the values used for the fields in the gzip header.
752
753 All other parameters that control the content of the gzip header will
754 be ignored if this parameter is set to 1.
755
756 This parameter defaults to 0.
757
758 =item C<< Comment => $comment >>
759
760 Stores the contents of C<$comment> in the COMMENT field in
761 the gzip header.
762 By default, no comment field is written to the gzip file.
763
764 If the C<-Strict> option is enabled, the comment can only consist of ISO
765 8859-1 characters plus line feed.
766
767 If the C<-Strict> option is disabled, the comment field can contain any
768 character except NULL. If any null characters are present, the field
769 will be truncated at the first NULL.
770
771 =item C<< Name => $string >>
772
773 Stores the contents of C<$string> in the gzip NAME header field. If
774 C<Name> is not specified, no gzip NAME field will be created.
775
776 If the C<-Strict> option is enabled, C<$string> can only consist of ISO
777 8859-1 characters.
778
779 If C<-Strict> is disabled, then C<$string> can contain any character
780 except NULL. If any null characters are present, the field will be
781 truncated at the first NULL.
782
783 =item C<< Time => $number >>
784
785 Sets the MTIME field in the gzip header to $number.
786
787 This field defaults to the time the C<IO::Compress::Gzip> object was created
788 if this option is not specified.
789
790 =item C<< TextFlag => 0|1 >>
791
792 This parameter controls the setting of the FLG.FTEXT bit in the gzip
793 header. It is used to signal that the data stored in the gzip file/buffer
794 is probably text.
795
796 The default is 0. 
797
798 =item C<< HeaderCRC => 0|1 >>
799
800 When true this parameter will set the FLG.FHCRC bit to 1 in the gzip header
801 and set the CRC16 header field to the CRC of the complete gzip header
802 except the CRC16 field itself.
803
804 B<Note> that gzip files created with the C<HeaderCRC> flag set to 1 cannot
805 be read by most, if not all, of the standard gunzip utilities, most
806 notably gzip version 1.2.4. You should therefore avoid using this option if
807 you want to maximize the portability of your gzip files.
808
809 This parameter defaults to 0.
810
811 =item C<< OS_Code => $value >>
812
813 Stores C<$value> in the gzip OS header field. A number between 0 and 255 is
814 valid.
815
816 If not specified, this parameter defaults to the OS code of the Operating
817 System this module was built on. The value 3 is used as a catch-all for all
818 Unix variants and unknown Operating Systems.
819
820 =item C<< ExtraField => $data >>
821
822 This parameter allows additional metadata to be stored in the ExtraField in
823 the gzip header. An RFC 1952 compliant ExtraField consists of zero or more
824 subfields. Each subfield consists of a two byte header followed by the
825 subfield data.
826
827 The list of subfields can be supplied in any of the following formats
828
829     -ExtraField => [$id1, $data1,
830                     $id2, $data2,
831                      ...
832                    ]
833     -ExtraField => [ [$id1 => $data1],
834                      [$id2 => $data2],
835                      ...
836                    ]
837     -ExtraField => { $id1 => $data1,
838                      $id2 => $data2,
839                      ...
840                    }
841
842 Where C<$id1>, C<$id2> are two byte subfield ID's. The second byte of
843 the ID cannot be 0, unless the C<Strict> option has been disabled.
844
845 If you use the hash syntax, you have no control over the order in which
846 the ExtraSubFields are stored, plus you cannot have SubFields with
847 duplicate ID.
848
849 Alternatively the list of subfields can by supplied as a scalar, thus
850
851     -ExtraField => $rawdata
852
853 If you use the raw format, and the C<Strict> option is enabled,
854 C<IO::Compress::Gzip> will check that C<$rawdata> consists of zero or more
855 conformant sub-fields. When C<Strict> is disabled, C<$rawdata> can
856 consist of any arbitrary byte stream.
857
858 The maximum size of the Extra Field 65535 bytes.
859
860 =item C<< ExtraFlags => $value >>
861
862 Sets the XFL byte in the gzip header to C<$value>.
863
864 If this option is not present, the value stored in XFL field will be
865 determined by the setting of the C<Level> option.
866
867 If C<< Level => Z_BEST_SPEED >> has been specified then XFL is set to 2.
868 If C<< Level => Z_BEST_COMPRESSION >> has been specified then XFL is set to 4.
869 Otherwise XFL is set to 0.
870
871 =item C<< Strict => 0|1 >>
872
873 C<Strict> will optionally police the values supplied with other options
874 to ensure they are compliant with RFC1952.
875
876 This option is enabled by default.
877
878 If C<Strict> is enabled the following behaviour will be policed:
879
880 =over 5
881
882 =item * 
883
884 The value supplied with the C<Name> option can only contain ISO 8859-1
885 characters.
886
887 =item * 
888
889 The value supplied with the C<Comment> option can only contain ISO 8859-1
890 characters plus line-feed.
891
892 =item *
893
894 The values supplied with the C<-Name> and C<-Comment> options cannot
895 contain multiple embedded nulls.
896
897 =item * 
898
899 If an C<ExtraField> option is specified and it is a simple scalar,
900 it must conform to the sub-field structure as defined in RFC 1952.
901
902 =item * 
903
904 If an C<ExtraField> option is specified the second byte of the ID will be
905 checked in each subfield to ensure that it does not contain the reserved
906 value 0x00.
907
908 =back
909
910 When C<Strict> is disabled the following behaviour will be policed:
911
912 =over 5
913
914 =item * 
915
916 The value supplied with C<-Name> option can contain
917 any character except NULL.
918
919 =item * 
920
921 The value supplied with C<-Comment> option can contain any character
922 except NULL.
923
924 =item *
925
926 The values supplied with the C<-Name> and C<-Comment> options can contain
927 multiple embedded nulls. The string written to the gzip header will
928 consist of the characters up to, but not including, the first embedded
929 NULL.
930
931 =item * 
932
933 If an C<ExtraField> option is specified and it is a simple scalar, the
934 structure will not be checked. The only error is if the length is too big.
935
936 =item * 
937
938 The ID header in an C<ExtraField> sub-field can consist of any two bytes.
939
940 =back
941
942 =back
943
944 =head2 Examples
945
946 TODO
947
948 =head1 Methods 
949
950 =head2 print
951
952 Usage is
953
954     $z->print($data)
955     print $z $data
956
957 Compresses and outputs the contents of the C<$data> parameter. This
958 has the same behaviour as the C<print> built-in.
959
960 Returns true if successful.
961
962 =head2 printf
963
964 Usage is
965
966     $z->printf($format, $data)
967     printf $z $format, $data
968
969 Compresses and outputs the contents of the C<$data> parameter.
970
971 Returns true if successful.
972
973 =head2 syswrite
974
975 Usage is
976
977     $z->syswrite $data
978     $z->syswrite $data, $length
979     $z->syswrite $data, $length, $offset
980
981 Compresses and outputs the contents of the C<$data> parameter.
982
983 Returns the number of uncompressed bytes written, or C<undef> if
984 unsuccessful.
985
986 =head2 write
987
988 Usage is
989
990     $z->write $data
991     $z->write $data, $length
992     $z->write $data, $length, $offset
993
994 Compresses and outputs the contents of the C<$data> parameter.
995
996 Returns the number of uncompressed bytes written, or C<undef> if
997 unsuccessful.
998
999 =head2 flush
1000
1001 Usage is
1002
1003     $z->flush;
1004     $z->flush($flush_type);
1005
1006 Flushes any pending compressed data to the output file/buffer.
1007
1008 This method takes an optional parameter, C<$flush_type>, that controls
1009 how the flushing will be carried out. By default the C<$flush_type>
1010 used is C<Z_FINISH>. Other valid values for C<$flush_type> are
1011 C<Z_NO_FLUSH>, C<Z_SYNC_FLUSH>, C<Z_FULL_FLUSH> and C<Z_BLOCK>. It is
1012 strongly recommended that you only set the C<flush_type> parameter if
1013 you fully understand the implications of what it does - overuse of C<flush>
1014 can seriously degrade the level of compression achieved. See the C<zlib>
1015 documentation for details.
1016
1017 Returns true on success.
1018
1019 =head2 tell
1020
1021 Usage is
1022
1023     $z->tell()
1024     tell $z
1025
1026 Returns the uncompressed file offset.
1027
1028 =head2 eof
1029
1030 Usage is
1031
1032     $z->eof();
1033     eof($z);
1034
1035 Returns true if the C<close> method has been called.
1036
1037 =head2 seek
1038
1039     $z->seek($position, $whence);
1040     seek($z, $position, $whence);
1041
1042 Provides a sub-set of the C<seek> functionality, with the restriction
1043 that it is only legal to seek forward in the output file/buffer.
1044 It is a fatal error to attempt to seek backward.
1045
1046 Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
1047
1048 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
1049 SEEK_CUR or SEEK_END.
1050
1051 Returns 1 on success, 0 on failure.
1052
1053 =head2 binmode
1054
1055 Usage is
1056
1057     $z->binmode
1058     binmode $z ;
1059
1060 This is a noop provided for completeness.
1061
1062 =head2 opened
1063
1064     $z->opened()
1065
1066 Returns true if the object currently refers to a opened file/buffer. 
1067
1068 =head2 autoflush
1069
1070     my $prev = $z->autoflush()
1071     my $prev = $z->autoflush(EXPR)
1072
1073 If the C<$z> object is associated with a file or a filehandle, this method
1074 returns the current autoflush setting for the underlying filehandle. If
1075 C<EXPR> is present, and is non-zero, it will enable flushing after every
1076 write/print operation.
1077
1078 If C<$z> is associated with a buffer, this method has no effect and always
1079 returns C<undef>.
1080
1081 B<Note> that the special variable C<$|> B<cannot> be used to set or
1082 retrieve the autoflush setting.
1083
1084 =head2 input_line_number
1085
1086     $z->input_line_number()
1087     $z->input_line_number(EXPR)
1088
1089 This method always returns C<undef> when compressing. 
1090
1091 =head2 fileno
1092
1093     $z->fileno()
1094     fileno($z)
1095
1096 If the C<$z> object is associated with a file or a filehandle, C<fileno>
1097 will return the underlying file descriptor. Once the C<close> method is
1098 called C<fileno> will return C<undef>.
1099
1100 If the C<$z> object is associated with a buffer, this method will return
1101 C<undef>.
1102
1103 =head2 close
1104
1105     $z->close() ;
1106     close $z ;
1107
1108 Flushes any pending compressed data and then closes the output file/buffer. 
1109
1110 For most versions of Perl this method will be automatically invoked if
1111 the IO::Compress::Gzip object is destroyed (either explicitly or by the
1112 variable with the reference to the object going out of scope). The
1113 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
1114 these cases, the C<close> method will be called automatically, but
1115 not until global destruction of all live objects when the program is
1116 terminating.
1117
1118 Therefore, if you want your scripts to be able to run on all versions
1119 of Perl, you should call C<close> explicitly and not rely on automatic
1120 closing.
1121
1122 Returns true on success, otherwise 0.
1123
1124 If the C<AutoClose> option has been enabled when the IO::Compress::Gzip
1125 object was created, and the object is associated with a file, the
1126 underlying file will also be closed.
1127
1128 =head2 newStream([OPTS])
1129
1130 Usage is
1131
1132     $z->newStream( [OPTS] )
1133
1134 Closes the current compressed data stream and starts a new one.
1135
1136 OPTS consists of any of the options that are available when creating
1137 the C<$z> object.
1138
1139 See the L</"Constructor Options"> section for more details.
1140
1141 =head2 deflateParams
1142
1143 Usage is
1144
1145     $z->deflateParams
1146
1147 TODO
1148
1149 =head1 Importing 
1150
1151 A number of symbolic constants are required by some methods in 
1152 C<IO::Compress::Gzip>. None are imported by default.
1153
1154 =over 5
1155
1156 =item :all
1157
1158 Imports C<gzip>, C<$GzipError> and all symbolic
1159 constants that can be used by C<IO::Compress::Gzip>. Same as doing this
1160
1161     use IO::Compress::Gzip qw(gzip $GzipError :constants) ;
1162
1163 =item :constants
1164
1165 Import all symbolic constants. Same as doing this
1166
1167     use IO::Compress::Gzip qw(:flush :level :strategy) ;
1168
1169 =item :flush
1170
1171 These symbolic constants are used by the C<flush> method.
1172
1173     Z_NO_FLUSH
1174     Z_PARTIAL_FLUSH
1175     Z_SYNC_FLUSH
1176     Z_FULL_FLUSH
1177     Z_FINISH
1178     Z_BLOCK
1179
1180 =item :level
1181
1182 These symbolic constants are used by the C<Level> option in the constructor.
1183
1184     Z_NO_COMPRESSION
1185     Z_BEST_SPEED
1186     Z_BEST_COMPRESSION
1187     Z_DEFAULT_COMPRESSION
1188
1189 =item :strategy
1190
1191 These symbolic constants are used by the C<Strategy> option in the constructor.
1192
1193     Z_FILTERED
1194     Z_HUFFMAN_ONLY
1195     Z_RLE
1196     Z_FIXED
1197     Z_DEFAULT_STRATEGY
1198
1199     
1200     
1201
1202 =back
1203
1204 =head1 EXAMPLES
1205
1206 =head2 Apache::GZip Revisited
1207
1208 See L<IO::Compress::FAQ|IO::Compress::FAQ/"Apache::GZip Revisited">
1209
1210 =head2 Working with Net::FTP
1211
1212 See L<IO::Compress::FAQ|IO::Compress::FAQ/"Compressed files and Net::FTP">
1213
1214 =head1 SEE ALSO
1215
1216 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::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
1217
1218 L<IO::Compress::FAQ|IO::Compress::FAQ>
1219
1220 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1221 L<Archive::Tar|Archive::Tar>,
1222 L<IO::Zlib|IO::Zlib>
1223
1224 For RFC 1950, 1951 and 1952 see 
1225 F<http://www.faqs.org/rfcs/rfc1950.html>,
1226 F<http://www.faqs.org/rfcs/rfc1951.html> and
1227 F<http://www.faqs.org/rfcs/rfc1952.html>
1228
1229 The I<zlib> compression library was written by Jean-loup Gailly
1230 F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
1231
1232 The primary site for the I<zlib> compression library is
1233 F<http://www.zlib.org>.
1234
1235 The primary site for gzip is F<http://www.gzip.org>.
1236
1237 =head1 AUTHOR
1238
1239 This module was written by Paul Marquess, F<pmqs@cpan.org>. 
1240
1241 =head1 MODIFICATION HISTORY
1242
1243 See the Changes file.
1244
1245 =head1 COPYRIGHT AND LICENSE
1246
1247 Copyright (c) 2005-2014 Paul Marquess. All rights reserved.
1248
1249 This program is free software; you can redistribute it and/or
1250 modify it under the same terms as Perl itself.
1251