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            When reading from a file or filehandle, set "binmode" before
176            reading.
177
178            Defaults to 0.
179
180       "Append => 0|1"
181            The behaviour of this option is dependent on the type of output
182            data stream.
183
184            ·    A Buffer
185
186                 If "Append" is enabled, all compressed data will be append to
187                 the end of the output buffer. Otherwise the output buffer
188                 will be cleared before any compressed data is written to it.
189
190            ·    A Filename
191
192                 If "Append" is enabled, the file will be opened in append
193                 mode. Otherwise the contents of the file, if any, will be
194                 truncated before any compressed data is written to it.
195
196            ·    A Filehandle
197
198                 If "Append" is enabled, the filehandle will be positioned to
199                 the end of the file via a call to "seek" before any
200                 compressed data is written to it.  Otherwise the file pointer
201                 will not be moved.
202
203            When "Append" is specified, and set to true, it will append all
204            compressed data to the output data stream.
205
206            So when the output is a filehandle it will carry out a seek to the
207            eof before writing any compressed data. If the output is a
208            filename, it will be opened for appending. If the output is a
209            buffer, all compressed data will be appended to the existing
210            buffer.
211
212            Conversely when "Append" is not specified, or it is present and is
213            set to false, it will operate as follows.
214
215            When the output is a filename, it will truncate the contents of
216            the file before writing any compressed data. If the output is a
217            filehandle its position will not be changed. If the output is a
218            buffer, it will be wiped before any compressed data is output.
219
220            Defaults to 0.
221
222   Examples
223       To read the contents of the file "file1.txt" and write the compressed
224       data to the file "file1.txt.1950".
225
226           use strict ;
227           use warnings ;
228           use IO::Compress::Deflate qw(deflate $DeflateError) ;
229
230           my $input = "file1.txt";
231           deflate $input => "$input.1950"
232               or die "deflate failed: $DeflateError\n";
233
234       To read from an existing Perl filehandle, $input, and write the
235       compressed data to a buffer, $buffer.
236
237           use strict ;
238           use warnings ;
239           use IO::Compress::Deflate qw(deflate $DeflateError) ;
240           use IO::File ;
241
242           my $input = new IO::File "<file1.txt"
243               or die "Cannot open 'file1.txt': $!\n" ;
244           my $buffer ;
245           deflate $input => \$buffer
246               or die "deflate failed: $DeflateError\n";
247
248       To compress all files in the directory "/my/home" that match "*.txt"
249       and store the compressed data in the same directory
250
251           use strict ;
252           use warnings ;
253           use IO::Compress::Deflate qw(deflate $DeflateError) ;
254
255           deflate '</my/home/*.txt>' => '<*.1950>'
256               or die "deflate failed: $DeflateError\n";
257
258       and if you want to compress each file one at a time, this will do the
259       trick
260
261           use strict ;
262           use warnings ;
263           use IO::Compress::Deflate qw(deflate $DeflateError) ;
264
265           for my $input ( glob "/my/home/*.txt" )
266           {
267               my $output = "$input.1950" ;
268               deflate $input => $output
269                   or die "Error compressing '$input': $DeflateError\n";
270           }
271

OO Interface

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

Methods

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

Importing

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

EXAMPLES

637   Apache::GZip Revisited
638       See IO::Compress::FAQ
639
640   Working with Net::FTP
641       See IO::Compress::FAQ
642

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-2013 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.16.3                      2013-05-19          IO::Compress::Deflate(3)