IO::Compress::Deflate(3pm)

1IO::Compress::Deflate(3U)ser Contributed Perl DocumentatiIoOn::Compress::Deflate(3)
2
3
4

NAME

6       IO::Compress::Deflate - Write RFC 1950 files/buffers
7

SYNOPSIS

9           use IO::Compress::Deflate qw(deflate $DeflateError) ;
10
11           my $status = deflate $input => $output [,OPTS]
12               or die "deflate failed: $DeflateError\n";
13
14           my $z = IO::Compress::Deflate->new( $output [,OPTS] )
15               or die "deflate failed: $DeflateError\n";
16
17           $z->print($string);
18           $z->printf($format, $string);
19           $z->write($string);
20           $z->syswrite($string [, $length, $offset]);
21           $z->flush();
22           $z->tell();
23           $z->eof();
24           $z->seek($position, $whence);
25           $z->binmode();
26           $z->fileno();
27           $z->opened();
28           $z->autoflush();
29           $z->input_line_number();
30           $z->newStream( [OPTS] );
31
32           $z->deflateParams();
33
34           $z->close() ;
35
36           $DeflateError ;
37
38           # IO::File mode
39
40           print $z $string;
41           printf $z $format, $string;
42           tell $z
43           eof $z
44           seek $z, $position, $whence
45           binmode $z
46           fileno $z
47           close $z ;
48

DESCRIPTION

50       This module provides a Perl interface that allows writing compressed
51       data to files or buffer as defined in RFC 1950.
52
53       For reading RFC 1950 files/buffers, see the companion module
54       IO::Uncompress::Inflate.
55

Functional Interface

57       A top-level function, "deflate", is provided to carry out "one-shot"
58       compression between buffers and/or files. For finer control over the
59       compression process, see the "OO Interface" section.
60
61           use IO::Compress::Deflate qw(deflate $DeflateError) ;
62
63           deflate $input_filename_or_reference => $output_filename_or_reference [,OPTS]
64               or die "deflate failed: $DeflateError\n";
65
66       The functional interface needs Perl5.005 or better.
67
68   deflate $input_filename_or_reference => $output_filename_or_reference [,
69       OPTS]
70       "deflate" expects at least two parameters, $input_filename_or_reference
71       and $output_filename_or_reference and zero or more optional parameters
72       (see "Optional Parameters")
73
74       The $input_filename_or_reference parameter
75
76       The parameter, $input_filename_or_reference, is used to define the
77       source of the uncompressed data.
78
79       It can take one of the following forms:
80
81       A filename
82            If the $input_filename_or_reference parameter is a simple scalar,
83            it is assumed to be a filename. This file will be opened for
84            reading and the input data will be read from it.
85
86       A filehandle
87            If the $input_filename_or_reference parameter is a filehandle, the
88            input data will be read from it.  The string '-' can be used as an
89            alias for standard input.
90
91       A scalar reference
92            If $input_filename_or_reference is a scalar reference, the input
93            data will be read from $$input_filename_or_reference.
94
95       An array reference
96            If $input_filename_or_reference is an array reference, each
97            element in the array must be a filename.
98
99            The input data will be read from each file in turn.
100
101            The complete array will be walked to ensure that it only contains
102            valid filenames before any data is compressed.
103
104       An Input FileGlob string
105            If $input_filename_or_reference is a string that is delimited by
106            the characters "<" and ">" "deflate" will assume that it is an
107            input fileglob string. The input is the list of files that match
108            the fileglob.
109
110            See File::GlobMapper for more details.
111
112       If the $input_filename_or_reference parameter is any other type,
113       "undef" will be returned.
114
115       The $output_filename_or_reference parameter
116
117       The parameter $output_filename_or_reference is used to control the
118       destination of the compressed data. This parameter can take one of
119       these forms.
120
121       A filename
122            If the $output_filename_or_reference parameter is a simple scalar,
123            it is assumed to be a filename.  This file will be opened for
124            writing and the compressed data will be written to it.
125
126       A filehandle
127            If the $output_filename_or_reference parameter is a filehandle,
128            the compressed data will be written to it.  The string '-' can be
129            used as an alias for standard output.
130
131       A scalar reference
132            If $output_filename_or_reference is a scalar reference, the
133            compressed data will be stored in $$output_filename_or_reference.
134
135       An Array Reference
136            If $output_filename_or_reference is an array reference, the
137            compressed data will be pushed onto the array.
138
139       An Output FileGlob
140            If $output_filename_or_reference is a string that is delimited by
141            the characters "<" and ">" "deflate" will assume that it is an
142            output fileglob string. The output is the list of files that match
143            the fileglob.
144
145            When $output_filename_or_reference is an fileglob string,
146            $input_filename_or_reference must also be a fileglob string.
147            Anything else is an error.
148
149            See File::GlobMapper for more details.
150
151       If the $output_filename_or_reference parameter is any other type,
152       "undef" will be returned.
153
154   Notes
155       When $input_filename_or_reference maps to multiple files/buffers and
156       $output_filename_or_reference is a single file/buffer the input
157       files/buffers will be stored in $output_filename_or_reference as a
158       concatenated series of compressed data streams.
159
160   Optional Parameters
161       The optional parameters for the one-shot function "deflate" are (for
162       the most part) identical to those used with the OO interface defined in
163       the "Constructor Options" section. The exceptions are listed below
164
165       "AutoClose => 0|1"
166            This option applies to any input or output data streams to
167            "deflate" that are filehandles.
168
169            If "AutoClose" is specified, and the value is true, it will result
170            in all input and/or output filehandles being closed once "deflate"
171            has completed.
172
173            This parameter defaults to 0.
174
175       "BinModeIn => 0|1"
176            This option is now a no-op. All files will be read in binmode.
177
178       "Append => 0|1"
179            The behaviour of this option is dependent on the type of output
180            data stream.
181
182            •    A Buffer
183
184                 If "Append" is enabled, all compressed data will be append to
185                 the end of the output buffer. Otherwise the output buffer
186                 will be cleared before any compressed data is written to it.
187
188            •    A Filename
189
190                 If "Append" is enabled, the file will be opened in append
191                 mode. Otherwise the contents of the file, if any, will be
192                 truncated before any compressed data is written to it.
193
194            •    A Filehandle
195
196                 If "Append" is enabled, the filehandle will be positioned to
197                 the end of the file via a call to "seek" before any
198                 compressed data is written to it.  Otherwise the file pointer
199                 will not be moved.
200
201            When "Append" is specified, and set to true, it will append all
202            compressed data to the output data stream.
203
204            So when the output is a filehandle it will carry out a seek to the
205            eof before writing any compressed data. If the output is a
206            filename, it will be opened for appending. If the output is a
207            buffer, all compressed data will be appended to the existing
208            buffer.
209
210            Conversely when "Append" is not specified, or it is present and is
211            set to false, it will operate as follows.
212
213            When the output is a filename, it will truncate the contents of
214            the file before writing any compressed data. If the output is a
215            filehandle its position will not be changed. If the output is a
216            buffer, it will be wiped before any compressed data is output.
217
218            Defaults to 0.
219
220   Examples
221       Here are a few example that show the capabilities of the module.
222
223       Streaming
224
225       This very simple command line example demonstrates the streaming
226       capabilities of the module.  The code reads data from STDIN, compresses
227       it, and writes the compressed data to STDOUT.
228
229           $ echo hello world | perl -MIO::Compress::Deflate=deflate -e 'deflate \*STDIN => \*STDOUT' >output.1950
230
231       The special filename "-" can be used as a standin for both "\*STDIN"
232       and "\*STDOUT", so the above can be rewritten as
233
234           $ echo hello world | perl -MIO::Compress::Deflate=deflate -e 'deflate "-" => "-"' >output.1950
235
236       Compressing a file from the filesystem
237
238       To read the contents of the file "file1.txt" and write the compressed
239       data to the file "file1.txt.1950".
240
241           use strict ;
242           use warnings ;
243           use IO::Compress::Deflate qw(deflate $DeflateError) ;
244
245           my $input = "file1.txt";
246           deflate $input => "$input.1950"
247               or die "deflate failed: $DeflateError\n";
248
249       Reading from a Filehandle and writing to an in-memory buffer
250
251       To read from an existing Perl filehandle, $input, and write the
252       compressed data to a buffer, $buffer.
253
254           use strict ;
255           use warnings ;
256           use IO::Compress::Deflate qw(deflate $DeflateError) ;
257           use IO::File ;
258
259           my $input = IO::File->new( "<file1.txt" )
260               or die "Cannot open 'file1.txt': $!\n" ;
261           my $buffer ;
262           deflate $input => \$buffer
263               or die "deflate failed: $DeflateError\n";
264
265       Compressing multiple files
266
267       To compress all files in the directory "/my/home" that match "*.txt"
268       and store the compressed data in the same directory
269
270           use strict ;
271           use warnings ;
272           use IO::Compress::Deflate qw(deflate $DeflateError) ;
273
274           deflate '</my/home/*.txt>' => '<*.1950>'
275               or die "deflate failed: $DeflateError\n";
276
277       and if you want to compress each file one at a time, this will do the
278       trick
279
280           use strict ;
281           use warnings ;
282           use IO::Compress::Deflate qw(deflate $DeflateError) ;
283
284           for my $input ( glob "/my/home/*.txt" )
285           {
286               my $output = "$input.1950" ;
287               deflate $input => $output
288                   or die "Error compressing '$input': $DeflateError\n";
289           }
290

OO Interface

292   Constructor
293       The format of the constructor for "IO::Compress::Deflate" is shown
294       below
295
296           my $z = IO::Compress::Deflate->new( $output [,OPTS] )
297               or die "IO::Compress::Deflate failed: $DeflateError\n";
298
299       It returns an "IO::Compress::Deflate" object on success and undef on
300       failure.  The variable $DeflateError will contain an error message on
301       failure.
302
303       If you are running Perl 5.005 or better the object, $z, returned from
304       IO::Compress::Deflate can be used exactly like an IO::File filehandle.
305       This means that all normal output file operations can be carried out
306       with $z.  For example, to write to a compressed file/buffer you can use
307       either of these forms
308
309           $z->print("hello world\n");
310           print $z "hello world\n";
311
312       The mandatory parameter $output is used to control the destination of
313       the compressed data. This parameter can take one of these forms.
314
315       A filename
316            If the $output parameter is a simple scalar, it is assumed to be a
317            filename. This file will be opened for writing and the compressed
318            data will be written to it.
319
320       A filehandle
321            If the $output parameter is a filehandle, the compressed data will
322            be written to it.  The string '-' can be used as an alias for
323            standard output.
324
325       A scalar reference
326            If $output is a scalar reference, the compressed data will be
327            stored in $$output.
328
329       If the $output parameter is any other type,
330       "IO::Compress::Deflate"::new will return undef.
331
332   Constructor Options
333       "OPTS" is any combination of zero or more the following options:
334
335       "AutoClose => 0|1"
336            This option is only valid when the $output parameter is a
337            filehandle. If specified, and the value is true, it will result in
338            the $output being closed once either the "close" method is called
339            or the "IO::Compress::Deflate" object is destroyed.
340
341            This parameter defaults to 0.
342
343       "Append => 0|1"
344            Opens $output in append mode.
345
346            The behaviour of this option is dependent on the type of $output.
347
348            •    A Buffer
349
350                 If $output is a buffer and "Append" is enabled, all
351                 compressed data will be append to the end of $output.
352                 Otherwise $output will be cleared before any data is written
353                 to it.
354
355            •    A Filename
356
357                 If $output is a filename and "Append" is enabled, the file
358                 will be opened in append mode. Otherwise the contents of the
359                 file, if any, will be truncated before any compressed data is
360                 written to it.
361
362            •    A Filehandle
363
364                 If $output is a filehandle, the file pointer will be
365                 positioned to the end of the file via a call to "seek" before
366                 any compressed data is written to it.  Otherwise the file
367                 pointer will not be moved.
368
369            This parameter defaults to 0.
370
371       "Merge => 0|1"
372            This option is used to compress input data and append it to an
373            existing compressed data stream in $output. The end result is a
374            single compressed data stream stored in $output.
375
376            It is a fatal error to attempt to use this option when $output is
377            not an RFC 1950 data stream.
378
379            There are a number of other limitations with the "Merge" option:
380
381            1.   This module needs to have been built with zlib 1.2.1 or
382                 better to work. A fatal error will be thrown if "Merge" is
383                 used with an older version of zlib.
384
385            2.   If $output is a file or a filehandle, it must be seekable.
386
387            This parameter defaults to 0.
388
389       -Level
390            Defines the compression level used by zlib. The value should
391            either be a number between 0 and 9 (0 means no compression and 9
392            is maximum compression), or one of the symbolic constants defined
393            below.
394
395               Z_NO_COMPRESSION
396               Z_BEST_SPEED
397               Z_BEST_COMPRESSION
398               Z_DEFAULT_COMPRESSION
399
400            The default is Z_DEFAULT_COMPRESSION.
401
402            Note, these constants are not imported by "IO::Compress::Deflate"
403            by default.
404
405                use IO::Compress::Deflate qw(:strategy);
406                use IO::Compress::Deflate qw(:constants);
407                use IO::Compress::Deflate qw(:all);
408
409       -Strategy
410            Defines the strategy used to tune the compression. Use one of the
411            symbolic constants defined below.
412
413               Z_FILTERED
414               Z_HUFFMAN_ONLY
415               Z_RLE
416               Z_FIXED
417               Z_DEFAULT_STRATEGY
418
419            The default is Z_DEFAULT_STRATEGY.
420
421       "Strict => 0|1"
422            This is a placeholder option.
423
424   Examples
425       TODO
426

Methods

428   print
429       Usage is
430
431           $z->print($data)
432           print $z $data
433
434       Compresses and outputs the contents of the $data parameter. This has
435       the same behaviour as the "print" built-in.
436
437       Returns true if successful.
438
439   printf
440       Usage is
441
442           $z->printf($format, $data)
443           printf $z $format, $data
444
445       Compresses and outputs the contents of the $data parameter.
446
447       Returns true if successful.
448
449   syswrite
450       Usage is
451
452           $z->syswrite $data
453           $z->syswrite $data, $length
454           $z->syswrite $data, $length, $offset
455
456       Compresses and outputs the contents of the $data parameter.
457
458       Returns the number of uncompressed bytes written, or "undef" if
459       unsuccessful.
460
461   write
462       Usage is
463
464           $z->write $data
465           $z->write $data, $length
466           $z->write $data, $length, $offset
467
468       Compresses and outputs the contents of the $data parameter.
469
470       Returns the number of uncompressed bytes written, or "undef" if
471       unsuccessful.
472
473   flush
474       Usage is
475
476           $z->flush;
477           $z->flush($flush_type);
478
479       Flushes any pending compressed data to the output file/buffer.
480
481       This method takes an optional parameter, $flush_type, that controls how
482       the flushing will be carried out. By default the $flush_type used is
483       "Z_FINISH". Other valid values for $flush_type are "Z_NO_FLUSH",
484       "Z_SYNC_FLUSH", "Z_FULL_FLUSH" and "Z_BLOCK". It is strongly
485       recommended that you only set the "flush_type" parameter if you fully
486       understand the implications of what it does - overuse of "flush" can
487       seriously degrade the level of compression achieved. See the "zlib"
488       documentation for details.
489
490       Returns true on success.
491
492   tell
493       Usage is
494
495           $z->tell()
496           tell $z
497
498       Returns the uncompressed file offset.
499
500   eof
501       Usage is
502
503           $z->eof();
504           eof($z);
505
506       Returns true if the "close" method has been called.
507
508   seek
509           $z->seek($position, $whence);
510           seek($z, $position, $whence);
511
512       Provides a sub-set of the "seek" functionality, with the restriction
513       that it is only legal to seek forward in the output file/buffer.  It is
514       a fatal error to attempt to seek backward.
515
516       Empty parts of the file/buffer will have NULL (0x00) bytes written to
517       them.
518
519       The $whence parameter takes one the usual values, namely SEEK_SET,
520       SEEK_CUR or SEEK_END.
521
522       Returns 1 on success, 0 on failure.
523
524   binmode
525       Usage is
526
527           $z->binmode
528           binmode $z ;
529
530       This is a noop provided for completeness.
531
532   opened
533           $z->opened()
534
535       Returns true if the object currently refers to a opened file/buffer.
536
537   autoflush
538           my $prev = $z->autoflush()
539           my $prev = $z->autoflush(EXPR)
540
541       If the $z object is associated with a file or a filehandle, this method
542       returns the current autoflush setting for the underlying filehandle. If
543       "EXPR" is present, and is non-zero, it will enable flushing after every
544       write/print operation.
545
546       If $z is associated with a buffer, this method has no effect and always
547       returns "undef".
548
549       Note that the special variable $| cannot be used to set or retrieve the
550       autoflush setting.
551
552   input_line_number
553           $z->input_line_number()
554           $z->input_line_number(EXPR)
555
556       This method always returns "undef" when compressing.
557
558   fileno
559           $z->fileno()
560           fileno($z)
561
562       If the $z object is associated with a file or a filehandle, "fileno"
563       will return the underlying file descriptor. Once the "close" method is
564       called "fileno" will return "undef".
565
566       If the $z object is associated with a buffer, this method will return
567       "undef".
568
569   close
570           $z->close() ;
571           close $z ;
572
573       Flushes any pending compressed data and then closes the output
574       file/buffer.
575
576       For most versions of Perl this method will be automatically invoked if
577       the IO::Compress::Deflate object is destroyed (either explicitly or by
578       the variable with the reference to the object going out of scope). The
579       exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In these
580       cases, the "close" method will be called automatically, but not until
581       global destruction of all live objects when the program is terminating.
582
583       Therefore, if you want your scripts to be able to run on all versions
584       of Perl, you should call "close" explicitly and not rely on automatic
585       closing.
586
587       Returns true on success, otherwise 0.
588
589       If the "AutoClose" option has been enabled when the
590       IO::Compress::Deflate object was created, and the object is associated
591       with a file, the underlying file will also be closed.
592
593   newStream([OPTS])
594       Usage is
595
596           $z->newStream( [OPTS] )
597
598       Closes the current compressed data stream and starts a new one.
599
600       OPTS consists of any of the options that are available when creating
601       the $z object.
602
603       See the "Constructor Options" section for more details.
604
605   deflateParams
606       Usage is
607
608           $z->deflateParams
609
610       TODO
611

Importing

613       A number of symbolic constants are required by some methods in
614       "IO::Compress::Deflate". None are imported by default.
615
616       :all Imports "deflate", $DeflateError and all symbolic constants that
617            can be used by "IO::Compress::Deflate". Same as doing this
618
619                use IO::Compress::Deflate qw(deflate $DeflateError :constants) ;
620
621       :constants
622            Import all symbolic constants. Same as doing this
623
624                use IO::Compress::Deflate qw(:flush :level :strategy) ;
625
626       :flush
627            These symbolic constants are used by the "flush" method.
628
629                Z_NO_FLUSH
630                Z_PARTIAL_FLUSH
631                Z_SYNC_FLUSH
632                Z_FULL_FLUSH
633                Z_FINISH
634                Z_BLOCK
635
636       :level
637            These symbolic constants are used by the "Level" option in the
638            constructor.
639
640                Z_NO_COMPRESSION
641                Z_BEST_SPEED
642                Z_BEST_COMPRESSION
643                Z_DEFAULT_COMPRESSION
644
645       :strategy
646            These symbolic constants are used by the "Strategy" option in the
647            constructor.
648
649                Z_FILTERED
650                Z_HUFFMAN_ONLY
651                Z_RLE
652                Z_FIXED
653                Z_DEFAULT_STRATEGY
654

EXAMPLES

656   Apache::GZip Revisited
657       See IO::Compress::FAQ
658
659   Working with Net::FTP
660       See IO::Compress::FAQ
661

SUPPORT

663       General feedback/questions/bug reports should be sent to
664       <https://github.com/pmqs/IO-Compress/issues> (preferred) or
665       <https://rt.cpan.org/Public/Dist/Display.html?Name=IO-Compress>.
666

AUTHOR

699       This module was written by Paul Marquess, "pmqs@cpan.org".
700

MODIFICATION HISTORY

702       See the Changes file.
703

COPYRIGHT AND LICENSE

705       Copyright (c) 2005-2023 Paul Marquess. All rights reserved.
706
707       This program is free software; you can redistribute it and/or modify it
708       under the same terms as Perl itself.
709
710
711
712perl v5.36.0                      2023-02-09          IO::Compress::Deflate(3)