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

OO Interface

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

Methods

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

Importing

591       A number of symbolic constants are required by some methods in
592       "IO::Compress::Deflate". None are imported by default.
593
594       :all Imports "deflate", $DeflateError and all symbolic constants that
595            can be used by "IO::Compress::Deflate". Same as doing this
596
597                use IO::Compress::Deflate qw(deflate $DeflateError :constants) ;
598
599       :constants
600            Import all symbolic constants. Same as doing this
601
602                use IO::Compress::Deflate qw(:flush :level :strategy) ;
603
604       :flush
605            These symbolic constants are used by the "flush" method.
606
607                Z_NO_FLUSH
608                Z_PARTIAL_FLUSH
609                Z_SYNC_FLUSH
610                Z_FULL_FLUSH
611                Z_FINISH
612                Z_BLOCK
613
614       :level
615            These symbolic constants are used by the "Level" option in the
616            constructor.
617
618                Z_NO_COMPRESSION
619                Z_BEST_SPEED
620                Z_BEST_COMPRESSION
621                Z_DEFAULT_COMPRESSION
622
623       :strategy
624            These symbolic constants are used by the "Strategy" option in the
625            constructor.
626
627                Z_FILTERED
628                Z_HUFFMAN_ONLY
629                Z_RLE
630                Z_FIXED
631                Z_DEFAULT_STRATEGY
632

EXAMPLES

634   Apache::GZip Revisited
635       See IO::Compress::FAQ
636
637   Working with Net::FTP
638       See IO::Compress::FAQ
639

AUTHOR

669       This module was written by Paul Marquess, "pmqs@cpan.org".
670

MODIFICATION HISTORY

672       See the Changes file.
673

COPYRIGHT AND LICENSE

675       Copyright (c) 2005-2019 Paul Marquess. All rights reserved.
676
677       This program is free software; you can redistribute it and/or modify it
678       under the same terms as Perl itself.
679
680
681
682perl v5.30.0                      2019-08-12          IO::Compress::Deflate(3)