"Fossies" - the Fresh Open Source Software Archive

Member "IO-Compress-2.093/lib/IO/Compress/RawDeflate.pm" (7 Dec 2019, 26961 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 "RawDeflate.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::RawDeflate ;
    2 
    3 # create RFC1951
    4 #
    5 use strict ;
    6 use warnings;
    7 use bytes;
    8 
    9 use IO::Compress::Base 2.093 ;
   10 use IO::Compress::Base::Common  2.093 qw(:Status );
   11 use IO::Compress::Adapter::Deflate 2.093 ;
   12 
   13 require Exporter ;
   14 
   15 our ($VERSION, @ISA, @EXPORT_OK, %DEFLATE_CONSTANTS, %EXPORT_TAGS, $RawDeflateError);
   16 
   17 $VERSION = '2.093';
   18 $RawDeflateError = '';
   19 
   20 @ISA = qw(IO::Compress::Base Exporter);
   21 @EXPORT_OK = qw( $RawDeflateError rawdeflate ) ;
   22 push @EXPORT_OK, @IO::Compress::Adapter::Deflate::EXPORT_OK ;
   23 
   24 %EXPORT_TAGS = %IO::Compress::Adapter::Deflate::DEFLATE_CONSTANTS;
   25 
   26 
   27 {
   28     my %seen;
   29     foreach (keys %EXPORT_TAGS )
   30     {
   31         push @{$EXPORT_TAGS{constants}}, 
   32                  grep { !$seen{$_}++ } 
   33                  @{ $EXPORT_TAGS{$_} }
   34     }
   35     $EXPORT_TAGS{all} = $EXPORT_TAGS{constants} ;
   36 }
   37 
   38 
   39 %DEFLATE_CONSTANTS = %EXPORT_TAGS;
   40 
   41 #push @{ $EXPORT_TAGS{all} }, @EXPORT_OK ;
   42 
   43 Exporter::export_ok_tags('all');
   44               
   45 
   46 
   47 sub new
   48 {
   49     my $class = shift ;
   50 
   51     my $obj = IO::Compress::Base::Common::createSelfTiedObject($class, \$RawDeflateError);
   52 
   53     return $obj->_create(undef, @_);
   54 }
   55 
   56 sub rawdeflate
   57 {
   58     my $obj = IO::Compress::Base::Common::createSelfTiedObject(undef, \$RawDeflateError);
   59     return $obj->_def(@_);
   60 }
   61 
   62 sub ckParams
   63 {
   64     my $self = shift ;
   65     my $got = shift;
   66 
   67     return 1 ;
   68 }
   69 
   70 sub mkComp
   71 {
   72     my $self = shift ;
   73     my $got = shift ;
   74 
   75     my ($obj, $errstr, $errno) = IO::Compress::Adapter::Deflate::mkCompObject(
   76                                                  $got->getValue('crc32'),
   77                                                  $got->getValue('adler32'),
   78                                                  $got->getValue('level'),
   79                                                  $got->getValue('strategy')
   80                                                  );
   81 
   82    return $self->saveErrorString(undef, $errstr, $errno)
   83        if ! defined $obj;
   84 
   85    return $obj;    
   86 }
   87 
   88 
   89 sub mkHeader
   90 {
   91     my $self = shift ;
   92     return '';
   93 }
   94 
   95 sub mkTrailer
   96 {
   97     my $self = shift ;
   98     return '';
   99 }
  100 
  101 sub mkFinalTrailer
  102 {
  103     return '';
  104 }
  105 
  106 
  107 #sub newHeader
  108 #{
  109 #    my $self = shift ;
  110 #    return '';
  111 #}
  112 
  113 sub getExtraParams
  114 {
  115     my $self = shift ;
  116     return getZlibParams();
  117 }
  118 
  119 use IO::Compress::Base::Common  2.093 qw(:Parse);
  120 use Compress::Raw::Zlib  2.093 qw(Z_DEFLATED Z_DEFAULT_COMPRESSION Z_DEFAULT_STRATEGY);
  121 our %PARAMS = (
  122             #'method'   => [IO::Compress::Base::Common::Parse_unsigned,  Z_DEFLATED],
  123             'level'     => [IO::Compress::Base::Common::Parse_signed,    Z_DEFAULT_COMPRESSION],
  124             'strategy'  => [IO::Compress::Base::Common::Parse_signed,    Z_DEFAULT_STRATEGY],
  125 
  126             'crc32'     => [IO::Compress::Base::Common::Parse_boolean,   0],
  127             'adler32'   => [IO::Compress::Base::Common::Parse_boolean,   0],
  128             'merge'     => [IO::Compress::Base::Common::Parse_boolean,   0], 
  129         );
  130         
  131 sub getZlibParams
  132 {
  133     return %PARAMS;    
  134 }
  135 
  136 sub getInverseClass
  137 {
  138     return ('IO::Uncompress::RawInflate', 
  139                 \$IO::Uncompress::RawInflate::RawInflateError);
  140 }
  141 
  142 sub getFileInfo
  143 {
  144     my $self = shift ;
  145     my $params = shift;
  146     my $file = shift ;
  147     
  148 }
  149 
  150 use Fcntl qw(SEEK_SET);
  151 
  152 sub createMerge
  153 {
  154     my $self = shift ;
  155     my $outValue = shift ;
  156     my $outType = shift ;
  157 
  158     my ($invClass, $error_ref) = $self->getInverseClass();
  159     eval "require $invClass" 
  160         or die "aaaahhhh" ;
  161 
  162     my $inf = $invClass->new( $outValue, 
  163                              Transparent => 0, 
  164                              #Strict     => 1,
  165                              AutoClose   => 0,
  166                              Scan        => 1)
  167        or return $self->saveErrorString(undef, "Cannot create InflateScan object: $$error_ref" ) ;
  168 
  169     my $end_offset = 0;
  170     $inf->scan() 
  171         or return $self->saveErrorString(undef, "Error Scanning: $$error_ref", $inf->errorNo) ;
  172     $inf->zap($end_offset) 
  173         or return $self->saveErrorString(undef, "Error Zapping: $$error_ref", $inf->errorNo) ;
  174 
  175     my $def = *$self->{Compress} = $inf->createDeflate();
  176 
  177     *$self->{Header} = *$inf->{Info}{Header};
  178     *$self->{UnCompSize} = *$inf->{UnCompSize}->clone();
  179     *$self->{CompSize} = *$inf->{CompSize}->clone();
  180     # TODO -- fix this
  181     #*$self->{CompSize} = new U64(0, *$self->{UnCompSize_32bit});
  182 
  183 
  184     if ( $outType eq 'buffer') 
  185       { substr( ${ *$self->{Buffer} }, $end_offset) = '' }
  186     elsif ($outType eq 'handle' || $outType eq 'filename') {
  187         *$self->{FH} = *$inf->{FH} ;
  188         delete *$inf->{FH};
  189         *$self->{FH}->flush() ;
  190         *$self->{Handle} = 1 if $outType eq 'handle';
  191 
  192         #seek(*$self->{FH}, $end_offset, SEEK_SET) 
  193         *$self->{FH}->seek($end_offset, SEEK_SET) 
  194             or return $self->saveErrorString(undef, $!, $!) ;
  195     }
  196 
  197     return $def ;
  198 }
  199 
  200 #### zlib specific methods
  201 
  202 sub deflateParams 
  203 {
  204     my $self = shift ;
  205 
  206     my $level = shift ;
  207     my $strategy = shift ;
  208 
  209     my $status = *$self->{Compress}->deflateParams(Level => $level, Strategy => $strategy) ;
  210     return $self->saveErrorString(0, *$self->{Compress}{Error}, *$self->{Compress}{ErrorNo})
  211         if $status == STATUS_ERROR;
  212 
  213     return 1;    
  214 }
  215 
  216 
  217 
  218 
  219 1;
  220 
  221 __END__
  222 
  223 =head1 NAME
  224 
  225 IO::Compress::RawDeflate - Write RFC 1951 files/buffers
  226 
  227 =head1 SYNOPSIS
  228 
  229     use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
  230 
  231     my $status = rawdeflate $input => $output [,OPTS]
  232         or die "rawdeflate failed: $RawDeflateError\n";
  233 
  234     my $z = new IO::Compress::RawDeflate $output [,OPTS]
  235         or die "rawdeflate failed: $RawDeflateError\n";
  236 
  237     $z->print($string);
  238     $z->printf($format, $string);
  239     $z->write($string);
  240     $z->syswrite($string [, $length, $offset]);
  241     $z->flush();
  242     $z->tell();
  243     $z->eof();
  244     $z->seek($position, $whence);
  245     $z->binmode();
  246     $z->fileno();
  247     $z->opened();
  248     $z->autoflush();
  249     $z->input_line_number();
  250     $z->newStream( [OPTS] );
  251 
  252     $z->deflateParams();
  253 
  254     $z->close() ;
  255 
  256     $RawDeflateError ;
  257 
  258     # IO::File mode
  259 
  260     print $z $string;
  261     printf $z $format, $string;
  262     tell $z
  263     eof $z
  264     seek $z, $position, $whence
  265     binmode $z
  266     fileno $z
  267     close $z ;
  268 
  269 =head1 DESCRIPTION
  270 
  271 This module provides a Perl interface that allows writing compressed
  272 data to files or buffer as defined in RFC 1951.
  273 
  274 Note that RFC 1951 data is not a good choice of compression format
  275 to use in isolation, especially if you want to auto-detect it.
  276 
  277 For reading RFC 1951 files/buffers, see the companion module
  278 L<IO::Uncompress::RawInflate|IO::Uncompress::RawInflate>.
  279 
  280 =head1 Functional Interface
  281 
  282 A top-level function, C<rawdeflate>, is provided to carry out
  283 "one-shot" compression between buffers and/or files. For finer
  284 control over the compression process, see the L</"OO Interface">
  285 section.
  286 
  287     use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
  288 
  289     rawdeflate $input_filename_or_reference => $output_filename_or_reference [,OPTS]
  290         or die "rawdeflate failed: $RawDeflateError\n";
  291 
  292 The functional interface needs Perl5.005 or better.
  293 
  294 =head2 rawdeflate $input_filename_or_reference => $output_filename_or_reference [, OPTS]
  295 
  296 C<rawdeflate> expects at least two parameters,
  297 C<$input_filename_or_reference> and C<$output_filename_or_reference>
  298 and zero or more optional parameters (see L</Optional Parameters>)
  299 
  300 =head3 The C<$input_filename_or_reference> parameter
  301 
  302 The parameter, C<$input_filename_or_reference>, is used to define the
  303 source of the uncompressed data.
  304 
  305 It can take one of the following forms:
  306 
  307 =over 5
  308 
  309 =item A filename
  310 
  311 If the C<$input_filename_or_reference> parameter is a simple scalar, it is
  312 assumed to be a filename. This file will be opened for reading and the
  313 input data will be read from it.
  314 
  315 =item A filehandle
  316 
  317 If the C<$input_filename_or_reference> parameter is a filehandle, the input
  318 data will be read from it.  The string '-' can be used as an alias for
  319 standard input.
  320 
  321 =item A scalar reference
  322 
  323 If C<$input_filename_or_reference> is a scalar reference, the input data
  324 will be read from C<$$input_filename_or_reference>.
  325 
  326 =item An array reference
  327 
  328 If C<$input_filename_or_reference> is an array reference, each element in
  329 the array must be a filename.
  330 
  331 The input data will be read from each file in turn.
  332 
  333 The complete array will be walked to ensure that it only
  334 contains valid filenames before any data is compressed.
  335 
  336 =item An Input FileGlob string
  337 
  338 If C<$input_filename_or_reference> is a string that is delimited by the
  339 characters "<" and ">" C<rawdeflate> will assume that it is an
  340 I<input fileglob string>. The input is the list of files that match the
  341 fileglob.
  342 
  343 See L<File::GlobMapper|File::GlobMapper> for more details.
  344 
  345 =back
  346 
  347 If the C<$input_filename_or_reference> parameter is any other type,
  348 C<undef> will be returned.
  349 
  350 =head3 The C<$output_filename_or_reference> parameter
  351 
  352 The parameter C<$output_filename_or_reference> is used to control the
  353 destination of the compressed data. This parameter can take one of
  354 these forms.
  355 
  356 =over 5
  357 
  358 =item A filename
  359 
  360 If the C<$output_filename_or_reference> parameter is a simple scalar, it is
  361 assumed to be a filename.  This file will be opened for writing and the
  362 compressed data will be written to it.
  363 
  364 =item A filehandle
  365 
  366 If the C<$output_filename_or_reference> parameter is a filehandle, the
  367 compressed data will be written to it.  The string '-' can be used as
  368 an alias for standard output.
  369 
  370 =item A scalar reference
  371 
  372 If C<$output_filename_or_reference> is a scalar reference, the
  373 compressed data will be stored in C<$$output_filename_or_reference>.
  374 
  375 =item An Array Reference
  376 
  377 If C<$output_filename_or_reference> is an array reference,
  378 the compressed data will be pushed onto the array.
  379 
  380 =item An Output FileGlob
  381 
  382 If C<$output_filename_or_reference> is a string that is delimited by the
  383 characters "<" and ">" C<rawdeflate> will assume that it is an
  384 I<output fileglob string>. The output is the list of files that match the
  385 fileglob.
  386 
  387 When C<$output_filename_or_reference> is an fileglob string,
  388 C<$input_filename_or_reference> must also be a fileglob string. Anything
  389 else is an error.
  390 
  391 See L<File::GlobMapper|File::GlobMapper> for more details.
  392 
  393 =back
  394 
  395 If the C<$output_filename_or_reference> parameter is any other type,
  396 C<undef> will be returned.
  397 
  398 =head2 Notes
  399 
  400 When C<$input_filename_or_reference> maps to multiple files/buffers and
  401 C<$output_filename_or_reference> is a single
  402 file/buffer the input files/buffers will be stored
  403 in C<$output_filename_or_reference> as a concatenated series of compressed data streams.
  404 
  405 =head2 Optional Parameters
  406 
  407 The optional parameters for the one-shot function C<rawdeflate>
  408 are (for the most part) identical to those used with the OO interface defined in the
  409 L</"Constructor Options"> section. The exceptions are listed below
  410 
  411 =over 5
  412 
  413 =item C<< AutoClose => 0|1 >>
  414 
  415 This option applies to any input or output data streams to
  416 C<rawdeflate> that are filehandles.
  417 
  418 If C<AutoClose> is specified, and the value is true, it will result in all
  419 input and/or output filehandles being closed once C<rawdeflate> has
  420 completed.
  421 
  422 This parameter defaults to 0.
  423 
  424 =item C<< BinModeIn => 0|1 >>
  425 
  426 This option is now a no-op. All files will be read in binmode.
  427 
  428 =item C<< Append => 0|1 >>
  429 
  430 The behaviour of this option is dependent on the type of output data
  431 stream.
  432 
  433 =over 5
  434 
  435 =item * A Buffer
  436 
  437 If C<Append> is enabled, all compressed data will be append to the end of
  438 the output buffer. Otherwise the output buffer will be cleared before any
  439 compressed data is written to it.
  440 
  441 =item * A Filename
  442 
  443 If C<Append> is enabled, the file will be opened in append mode. Otherwise
  444 the contents of the file, if any, will be truncated before any compressed
  445 data is written to it.
  446 
  447 =item * A Filehandle
  448 
  449 If C<Append> is enabled, the filehandle will be positioned to the end of
  450 the file via a call to C<seek> before any compressed data is
  451 written to it.  Otherwise the file pointer will not be moved.
  452 
  453 =back
  454 
  455 When C<Append> is specified, and set to true, it will I<append> all compressed
  456 data to the output data stream.
  457 
  458 So when the output is a filehandle it will carry out a seek to the eof
  459 before writing any compressed data. If the output is a filename, it will be opened for
  460 appending. If the output is a buffer, all compressed data will be
  461 appended to the existing buffer.
  462 
  463 Conversely when C<Append> is not specified, or it is present and is set to
  464 false, it will operate as follows.
  465 
  466 When the output is a filename, it will truncate the contents of the file
  467 before writing any compressed data. If the output is a filehandle
  468 its position will not be changed. If the output is a buffer, it will be
  469 wiped before any compressed data is output.
  470 
  471 Defaults to 0.
  472 
  473 =back
  474 
  475 =head2 Examples
  476 
  477 Here are a few example that show the capabilities of the module.
  478 
  479 =head3 Streaming
  480 
  481 This very simple command line example demonstrates the streaming capabilities of the module.
  482 The code reads data from STDIN, compresses it, and writes the compressed data to STDOUT.
  483 
  484     $ echo hello world | perl -MIO::Compress::RawDeflate=rawdeflate -e 'rawdeflate \*STDIN => \*STDOUT' >output.1951
  485 
  486 The special filename "-" can be used as a standin for both C<\*STDIN> and C<\*STDOUT>,
  487 so the above can be rewritten as
  488 
  489     $ echo hello world | perl -MIO::Compress::RawDeflate=rawdeflate -e 'rawdeflate "-" => "-"' >output.1951
  490 
  491 =head3 Compressing a file from the filesystem
  492 
  493 To read the contents of the file C<file1.txt> and write the compressed
  494 data to the file C<file1.txt.1951>.
  495 
  496     use strict ;
  497     use warnings ;
  498     use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
  499 
  500     my $input = "file1.txt";
  501     rawdeflate $input => "$input.1951"
  502         or die "rawdeflate failed: $RawDeflateError\n";
  503 
  504 =head3 Reading from a Filehandle and writing to an in-memory buffer
  505 
  506 To read from an existing Perl filehandle, C<$input>, and write the
  507 compressed data to a buffer, C<$buffer>.
  508 
  509     use strict ;
  510     use warnings ;
  511     use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
  512     use IO::File ;
  513 
  514     my $input = new IO::File "<file1.txt"
  515         or die "Cannot open 'file1.txt': $!\n" ;
  516     my $buffer ;
  517     rawdeflate $input => \$buffer
  518         or die "rawdeflate failed: $RawDeflateError\n";
  519 
  520 =head3 Compressing multiple files
  521 
  522 To compress all files in the directory "/my/home" that match "*.txt"
  523 and store the compressed data in the same directory
  524 
  525     use strict ;
  526     use warnings ;
  527     use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
  528 
  529     rawdeflate '</my/home/*.txt>' => '<*.1951>'
  530         or die "rawdeflate failed: $RawDeflateError\n";
  531 
  532 and if you want to compress each file one at a time, this will do the trick
  533 
  534     use strict ;
  535     use warnings ;
  536     use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
  537 
  538     for my $input ( glob "/my/home/*.txt" )
  539     {
  540         my $output = "$input.1951" ;
  541         rawdeflate $input => $output
  542             or die "Error compressing '$input': $RawDeflateError\n";
  543     }
  544 
  545 =head1 OO Interface
  546 
  547 =head2 Constructor
  548 
  549 The format of the constructor for C<IO::Compress::RawDeflate> is shown below
  550 
  551     my $z = new IO::Compress::RawDeflate $output [,OPTS]
  552         or die "IO::Compress::RawDeflate failed: $RawDeflateError\n";
  553 
  554 It returns an C<IO::Compress::RawDeflate> object on success and undef on failure.
  555 The variable C<$RawDeflateError> will contain an error message on failure.
  556 
  557 If you are running Perl 5.005 or better the object, C<$z>, returned from
  558 IO::Compress::RawDeflate can be used exactly like an L<IO::File|IO::File> filehandle.
  559 This means that all normal output file operations can be carried out
  560 with C<$z>.
  561 For example, to write to a compressed file/buffer you can use either of
  562 these forms
  563 
  564     $z->print("hello world\n");
  565     print $z "hello world\n";
  566 
  567 The mandatory parameter C<$output> is used to control the destination
  568 of the compressed data. This parameter can take one of these forms.
  569 
  570 =over 5
  571 
  572 =item A filename
  573 
  574 If the C<$output> parameter is a simple scalar, it is assumed to be a
  575 filename. This file will be opened for writing and the compressed data
  576 will be written to it.
  577 
  578 =item A filehandle
  579 
  580 If the C<$output> parameter is a filehandle, the compressed data will be
  581 written to it.
  582 The string '-' can be used as an alias for standard output.
  583 
  584 =item A scalar reference
  585 
  586 If C<$output> is a scalar reference, the compressed data will be stored
  587 in C<$$output>.
  588 
  589 =back
  590 
  591 If the C<$output> parameter is any other type, C<IO::Compress::RawDeflate>::new will
  592 return undef.
  593 
  594 =head2 Constructor Options
  595 
  596 C<OPTS> is any combination of zero or more the following options:
  597 
  598 =over 5
  599 
  600 =item C<< AutoClose => 0|1 >>
  601 
  602 This option is only valid when the C<$output> parameter is a filehandle. If
  603 specified, and the value is true, it will result in the C<$output> being
  604 closed once either the C<close> method is called or the C<IO::Compress::RawDeflate>
  605 object is destroyed.
  606 
  607 This parameter defaults to 0.
  608 
  609 =item C<< Append => 0|1 >>
  610 
  611 Opens C<$output> in append mode.
  612 
  613 The behaviour of this option is dependent on the type of C<$output>.
  614 
  615 =over 5
  616 
  617 =item * A Buffer
  618 
  619 If C<$output> is a buffer and C<Append> is enabled, all compressed data
  620 will be append to the end of C<$output>. Otherwise C<$output> will be
  621 cleared before any data is written to it.
  622 
  623 =item * A Filename
  624 
  625 If C<$output> is a filename and C<Append> is enabled, the file will be
  626 opened in append mode. Otherwise the contents of the file, if any, will be
  627 truncated before any compressed data is written to it.
  628 
  629 =item * A Filehandle
  630 
  631 If C<$output> is a filehandle, the file pointer will be positioned to the
  632 end of the file via a call to C<seek> before any compressed data is written
  633 to it.  Otherwise the file pointer will not be moved.
  634 
  635 =back
  636 
  637 This parameter defaults to 0.
  638 
  639 =item C<< Merge => 0|1 >>
  640 
  641 This option is used to compress input data and append it to an existing
  642 compressed data stream in C<$output>. The end result is a single compressed
  643 data stream stored in C<$output>.
  644 
  645 It is a fatal error to attempt to use this option when C<$output> is not an
  646 RFC 1951 data stream.
  647 
  648 There are a number of other limitations with the C<Merge> option:
  649 
  650 =over 5
  651 
  652 =item 1
  653 
  654 This module needs to have been built with zlib 1.2.1 or better to work. A
  655 fatal error will be thrown if C<Merge> is used with an older version of
  656 zlib.
  657 
  658 =item 2
  659 
  660 If C<$output> is a file or a filehandle, it must be seekable.
  661 
  662 =back
  663 
  664 This parameter defaults to 0.
  665 
  666 =item -Level
  667 
  668 Defines the compression level used by zlib. The value should either be
  669 a number between 0 and 9 (0 means no compression and 9 is maximum
  670 compression), or one of the symbolic constants defined below.
  671 
  672    Z_NO_COMPRESSION
  673    Z_BEST_SPEED
  674    Z_BEST_COMPRESSION
  675    Z_DEFAULT_COMPRESSION
  676 
  677 The default is Z_DEFAULT_COMPRESSION.
  678 
  679 Note, these constants are not imported by C<IO::Compress::RawDeflate> by default.
  680 
  681     use IO::Compress::RawDeflate qw(:strategy);
  682     use IO::Compress::RawDeflate qw(:constants);
  683     use IO::Compress::RawDeflate qw(:all);
  684 
  685 =item -Strategy
  686 
  687 Defines the strategy used to tune the compression. Use one of the symbolic
  688 constants defined below.
  689 
  690    Z_FILTERED
  691    Z_HUFFMAN_ONLY
  692    Z_RLE
  693    Z_FIXED
  694    Z_DEFAULT_STRATEGY
  695 
  696 The default is Z_DEFAULT_STRATEGY.
  697 
  698 =item C<< Strict => 0|1 >>
  699 
  700 This is a placeholder option.
  701 
  702 =back
  703 
  704 =head2 Examples
  705 
  706 TODO
  707 
  708 =head1 Methods
  709 
  710 =head2 print
  711 
  712 Usage is
  713 
  714     $z->print($data)
  715     print $z $data
  716 
  717 Compresses and outputs the contents of the C<$data> parameter. This
  718 has the same behaviour as the C<print> built-in.
  719 
  720 Returns true if successful.
  721 
  722 =head2 printf
  723 
  724 Usage is
  725 
  726     $z->printf($format, $data)
  727     printf $z $format, $data
  728 
  729 Compresses and outputs the contents of the C<$data> parameter.
  730 
  731 Returns true if successful.
  732 
  733 =head2 syswrite
  734 
  735 Usage is
  736 
  737     $z->syswrite $data
  738     $z->syswrite $data, $length
  739     $z->syswrite $data, $length, $offset
  740 
  741 Compresses and outputs the contents of the C<$data> parameter.
  742 
  743 Returns the number of uncompressed bytes written, or C<undef> if
  744 unsuccessful.
  745 
  746 =head2 write
  747 
  748 Usage is
  749 
  750     $z->write $data
  751     $z->write $data, $length
  752     $z->write $data, $length, $offset
  753 
  754 Compresses and outputs the contents of the C<$data> parameter.
  755 
  756 Returns the number of uncompressed bytes written, or C<undef> if
  757 unsuccessful.
  758 
  759 =head2 flush
  760 
  761 Usage is
  762 
  763     $z->flush;
  764     $z->flush($flush_type);
  765 
  766 Flushes any pending compressed data to the output file/buffer.
  767 
  768 This method takes an optional parameter, C<$flush_type>, that controls
  769 how the flushing will be carried out. By default the C<$flush_type>
  770 used is C<Z_FINISH>. Other valid values for C<$flush_type> are
  771 C<Z_NO_FLUSH>, C<Z_SYNC_FLUSH>, C<Z_FULL_FLUSH> and C<Z_BLOCK>. It is
  772 strongly recommended that you only set the C<flush_type> parameter if
  773 you fully understand the implications of what it does - overuse of C<flush>
  774 can seriously degrade the level of compression achieved. See the C<zlib>
  775 documentation for details.
  776 
  777 Returns true on success.
  778 
  779 =head2 tell
  780 
  781 Usage is
  782 
  783     $z->tell()
  784     tell $z
  785 
  786 Returns the uncompressed file offset.
  787 
  788 =head2 eof
  789 
  790 Usage is
  791 
  792     $z->eof();
  793     eof($z);
  794 
  795 Returns true if the C<close> method has been called.
  796 
  797 =head2 seek
  798 
  799     $z->seek($position, $whence);
  800     seek($z, $position, $whence);
  801 
  802 Provides a sub-set of the C<seek> functionality, with the restriction
  803 that it is only legal to seek forward in the output file/buffer.
  804 It is a fatal error to attempt to seek backward.
  805 
  806 Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
  807 
  808 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
  809 SEEK_CUR or SEEK_END.
  810 
  811 Returns 1 on success, 0 on failure.
  812 
  813 =head2 binmode
  814 
  815 Usage is
  816 
  817     $z->binmode
  818     binmode $z ;
  819 
  820 This is a noop provided for completeness.
  821 
  822 =head2 opened
  823 
  824     $z->opened()
  825 
  826 Returns true if the object currently refers to a opened file/buffer.
  827 
  828 =head2 autoflush
  829 
  830     my $prev = $z->autoflush()
  831     my $prev = $z->autoflush(EXPR)
  832 
  833 If the C<$z> object is associated with a file or a filehandle, this method
  834 returns the current autoflush setting for the underlying filehandle. If
  835 C<EXPR> is present, and is non-zero, it will enable flushing after every
  836 write/print operation.
  837 
  838 If C<$z> is associated with a buffer, this method has no effect and always
  839 returns C<undef>.
  840 
  841 B<Note> that the special variable C<$|> B<cannot> be used to set or
  842 retrieve the autoflush setting.
  843 
  844 =head2 input_line_number
  845 
  846     $z->input_line_number()
  847     $z->input_line_number(EXPR)
  848 
  849 This method always returns C<undef> when compressing.
  850 
  851 =head2 fileno
  852 
  853     $z->fileno()
  854     fileno($z)
  855 
  856 If the C<$z> object is associated with a file or a filehandle, C<fileno>
  857 will return the underlying file descriptor. Once the C<close> method is
  858 called C<fileno> will return C<undef>.
  859 
  860 If the C<$z> object is associated with a buffer, this method will return
  861 C<undef>.
  862 
  863 =head2 close
  864 
  865     $z->close() ;
  866     close $z ;
  867 
  868 Flushes any pending compressed data and then closes the output file/buffer.
  869 
  870 For most versions of Perl this method will be automatically invoked if
  871 the IO::Compress::RawDeflate object is destroyed (either explicitly or by the
  872 variable with the reference to the object going out of scope). The
  873 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
  874 these cases, the C<close> method will be called automatically, but
  875 not until global destruction of all live objects when the program is
  876 terminating.
  877 
  878 Therefore, if you want your scripts to be able to run on all versions
  879 of Perl, you should call C<close> explicitly and not rely on automatic
  880 closing.
  881 
  882 Returns true on success, otherwise 0.
  883 
  884 If the C<AutoClose> option has been enabled when the IO::Compress::RawDeflate
  885 object was created, and the object is associated with a file, the
  886 underlying file will also be closed.
  887 
  888 =head2 newStream([OPTS])
  889 
  890 Usage is
  891 
  892     $z->newStream( [OPTS] )
  893 
  894 Closes the current compressed data stream and starts a new one.
  895 
  896 OPTS consists of any of the options that are available when creating
  897 the C<$z> object.
  898 
  899 See the L</"Constructor Options"> section for more details.
  900 
  901 =head2 deflateParams
  902 
  903 Usage is
  904 
  905     $z->deflateParams
  906 
  907 TODO
  908 
  909 =head1 Importing
  910 
  911 A number of symbolic constants are required by some methods in
  912 C<IO::Compress::RawDeflate>. None are imported by default.
  913 
  914 =over 5
  915 
  916 =item :all
  917 
  918 Imports C<rawdeflate>, C<$RawDeflateError> and all symbolic
  919 constants that can be used by C<IO::Compress::RawDeflate>. Same as doing this
  920 
  921     use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError :constants) ;
  922 
  923 =item :constants
  924 
  925 Import all symbolic constants. Same as doing this
  926 
  927     use IO::Compress::RawDeflate qw(:flush :level :strategy) ;
  928 
  929 =item :flush
  930 
  931 These symbolic constants are used by the C<flush> method.
  932 
  933     Z_NO_FLUSH
  934     Z_PARTIAL_FLUSH
  935     Z_SYNC_FLUSH
  936     Z_FULL_FLUSH
  937     Z_FINISH
  938     Z_BLOCK
  939 
  940 =item :level
  941 
  942 These symbolic constants are used by the C<Level> option in the constructor.
  943 
  944     Z_NO_COMPRESSION
  945     Z_BEST_SPEED
  946     Z_BEST_COMPRESSION
  947     Z_DEFAULT_COMPRESSION
  948 
  949 =item :strategy
  950 
  951 These symbolic constants are used by the C<Strategy> option in the constructor.
  952 
  953     Z_FILTERED
  954     Z_HUFFMAN_ONLY
  955     Z_RLE
  956     Z_FIXED
  957     Z_DEFAULT_STRATEGY
  958 
  959 =back
  960 
  961 =head1 EXAMPLES
  962 
  963 =head2 Apache::GZip Revisited
  964 
  965 See L<IO::Compress::FAQ|IO::Compress::FAQ/"Apache::GZip Revisited">
  966 
  967 =head2 Working with Net::FTP
  968 
  969 See L<IO::Compress::FAQ|IO::Compress::FAQ/"Compressed files and Net::FTP">
  970 
  971 =head1 SUPPORT
  972 
  973 General feedback/questions/bug reports should be sent to 
  974 L<https://github.com/pmqs/IO-Compress/issues> (preferred) or
  975 L<https://rt.cpan.org/Public/Dist/Display.html?Name=IO-Compress>.
  976 
  977 =head1 SEE ALSO
  978 
  979 L<Compress::Zlib>, L<IO::Compress::Gzip>, L<IO::Uncompress::Gunzip>, L<IO::Compress::Deflate>, L<IO::Uncompress::Inflate>, 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>
  980 
  981 L<IO::Compress::FAQ|IO::Compress::FAQ>
  982 
  983 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
  984 L<Archive::Tar|Archive::Tar>,
  985 L<IO::Zlib|IO::Zlib>
  986 
  987 For RFC 1950, 1951 and 1952 see
  988 L<http://www.faqs.org/rfcs/rfc1950.html>,
  989 L<http://www.faqs.org/rfcs/rfc1951.html> and
  990 L<http://www.faqs.org/rfcs/rfc1952.html>
  991 
  992 The I<zlib> compression library was written by Jean-loup Gailly
  993 C<gzip@prep.ai.mit.edu> and Mark Adler C<madler@alumni.caltech.edu>.
  994 
  995 The primary site for the I<zlib> compression library is
  996 L<http://www.zlib.org>.
  997 
  998 The primary site for gzip is L<http://www.gzip.org>.
  999 
 1000 =head1 AUTHOR
 1001 
 1002 This module was written by Paul Marquess, C<pmqs@cpan.org>.
 1003 
 1004 =head1 MODIFICATION HISTORY
 1005 
 1006 See the Changes file.
 1007 
 1008 =head1 COPYRIGHT AND LICENSE
 1009 
 1010 Copyright (c) 2005-2019 Paul Marquess. All rights reserved.
 1011 
 1012 This program is free software; you can redistribute it and/or
 1013 modify it under the same terms as Perl itself.
 1014