IO::Compress::Deflate(3pm)

1IO::Compress::Deflate(3pPme)rl Programmers Reference GuiIdOe::Compress::Deflate(3pm)
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 => $output [,OPTS]
64               or die "deflate failed: $DeflateError\n";
65
66       The functional interface needs Perl5.005 or better.
67
68   deflate $input => $output [, OPTS]
69       "deflate" expects at least two parameters, $input and $output.
70
71       The $input parameter
72
73       The parameter, $input, is used to define the source of the uncompressed
74       data.
75
76       It can take one of the following forms:
77
78       A filename
79            If the $input parameter is a simple scalar, it is assumed to be a
80            filename. This file will be opened for reading and the input data
81            will be read from it.
82
83       A filehandle
84            If the $input parameter is a filehandle, the input data will be
85            read from it.  The string '-' can be used as an alias for standard
86            input.
87
88       A scalar reference
89            If $input is a scalar reference, the input data will be read from
90            $$input.
91
92       An array reference
93            If $input is an array reference, each element in the array must be
94            a filename.
95
96            The input data will be read from each file in turn.
97
98            The complete array will be walked to ensure that it only contains
99            valid filenames before any data is compressed.
100
101       An Input FileGlob string
102            If $input is a string that is delimited by the characters "<" and
103            ">" "deflate" will assume that it is an input fileglob string. The
104            input is the list of files that match the fileglob.
105
106            If the fileglob does not match any files ...
107
108            See File::GlobMapper for more details.
109
110       If the $input parameter is any other type, "undef" will be returned.
111
112       The $output parameter
113
114       The parameter $output is used to control the destination of the
115       compressed data. This parameter can take one of these forms.
116
117       A filename
118            If the $output parameter is a simple scalar, it is assumed to be a
119            filename.  This file will be opened for writing and the compressed
120            data will be written to it.
121
122       A filehandle
123            If the $output parameter is a filehandle, the compressed data will
124            be written to it.  The string '-' can be used as an alias for
125            standard output.
126
127       A scalar reference
128            If $output is a scalar reference, the compressed data will be
129            stored in $$output.
130
131       An Array Reference
132            If $output is an array reference, the compressed data will be
133            pushed onto the array.
134
135       An Output FileGlob
136            If $output is a string that is delimited by the characters "<" and
137            ">" "deflate" will assume that it is an output fileglob string.
138            The output is the list of files that match the fileglob.
139
140            When $output is an fileglob string, $input must also be a fileglob
141            string. Anything else is an error.
142
143       If the $output parameter is any other type, "undef" will be returned.
144
145   Notes
146       When $input maps to multiple files/buffers and $output is a single
147       file/buffer the input files/buffers will be stored in $output as a
148       concatenated series of compressed data streams.
149
150   Optional Parameters
151       Unless specified below, the optional parameters for "deflate", "OPTS",
152       are the same as those used with the OO interface defined in the
153       "Constructor Options" section below.
154
155       "AutoClose => 0|1"
156            This option applies to any input or output data streams to
157            "deflate" that are filehandles.
158
159            If "AutoClose" is specified, and the value is true, it will result
160            in all input and/or output filehandles being closed once "deflate"
161            has completed.
162
163            This parameter defaults to 0.
164
165       "BinModeIn => 0|1"
166            When reading from a file or filehandle, set "binmode" before
167            reading.
168
169            Defaults to 0.
170
171       "Append => 0|1"
172            TODO
173
174   Examples
175       To read the contents of the file "file1.txt" and write the compressed
176       data to the file "file1.txt.1950".
177
178           use strict ;
179           use warnings ;
180           use IO::Compress::Deflate qw(deflate $DeflateError) ;
181
182           my $input = "file1.txt";
183           deflate $input => "$input.1950"
184               or die "deflate failed: $DeflateError\n";
185
186       To read from an existing Perl filehandle, $input, and write the
187       compressed data to a buffer, $buffer.
188
189           use strict ;
190           use warnings ;
191           use IO::Compress::Deflate qw(deflate $DeflateError) ;
192           use IO::File ;
193
194           my $input = new IO::File "<file1.txt"
195               or die "Cannot open 'file1.txt': $!\n" ;
196           my $buffer ;
197           deflate $input => \$buffer
198               or die "deflate failed: $DeflateError\n";
199
200       To compress all files in the directory "/my/home" that match "*.txt"
201       and store the compressed data in the same directory
202
203           use strict ;
204           use warnings ;
205           use IO::Compress::Deflate qw(deflate $DeflateError) ;
206
207           deflate '</my/home/*.txt>' => '<*.1950>'
208               or die "deflate failed: $DeflateError\n";
209
210       and if you want to compress each file one at a time, this will do the
211       trick
212
213           use strict ;
214           use warnings ;
215           use IO::Compress::Deflate qw(deflate $DeflateError) ;
216
217           for my $input ( glob "/my/home/*.txt" )
218           {
219               my $output = "$input.1950" ;
220               deflate $input => $output
221                   or die "Error compressing '$input': $DeflateError\n";
222           }
223

OO Interface

225   Constructor
226       The format of the constructor for "IO::Compress::Deflate" is shown
227       below
228
229           my $z = new IO::Compress::Deflate $output [,OPTS]
230               or die "IO::Compress::Deflate failed: $DeflateError\n";
231
232       It returns an "IO::Compress::Deflate" object on success and undef on
233       failure.  The variable $DeflateError will contain an error message on
234       failure.
235
236       If you are running Perl 5.005 or better the object, $z, returned from
237       IO::Compress::Deflate can be used exactly like an IO::File filehandle.
238       This means that all normal output file operations can be carried out
239       with $z.  For example, to write to a compressed file/buffer you can use
240       either of these forms
241
242           $z->print("hello world\n");
243           print $z "hello world\n";
244
245       The mandatory parameter $output is used to control the destination of
246       the compressed data. This parameter can take one of these forms.
247
248       A filename
249            If the $output parameter is a simple scalar, it is assumed to be a
250            filename. This file will be opened for writing and the compressed
251            data will be written to it.
252
253       A filehandle
254            If the $output parameter is a filehandle, the compressed data will
255            be written to it.  The string '-' can be used as an alias for
256            standard output.
257
258       A scalar reference
259            If $output is a scalar reference, the compressed data will be
260            stored in $$output.
261
262       If the $output parameter is any other type,
263       "IO::Compress::Deflate"::new will return undef.
264
265   Constructor Options
266       "OPTS" is any combination of the following options:
267
268       "AutoClose => 0|1"
269            This option is only valid when the $output parameter is a
270            filehandle. If specified, and the value is true, it will result in
271            the $output being closed once either the "close" method is called
272            or the "IO::Compress::Deflate" object is destroyed.
273
274            This parameter defaults to 0.
275
276       "Append => 0|1"
277            Opens $output in append mode.
278
279            The behaviour of this option is dependent on the type of $output.
280
281            ·    A Buffer
282
283                 If $output is a buffer and "Append" is enabled, all
284                 compressed data will be append to the end if $output.
285                 Otherwise $output will be cleared before any data is written
286                 to it.
287
288            ·    A Filename
289
290                 If $output is a filename and "Append" is enabled, the file
291                 will be opened in append mode. Otherwise the contents of the
292                 file, if any, will be truncated before any compressed data is
293                 written to it.
294
295            ·    A Filehandle
296
297                 If $output is a filehandle, the file pointer will be
298                 positioned to the end of the file via a call to "seek" before
299                 any compressed data is written to it.  Otherwise the file
300                 pointer will not be moved.
301
302            This parameter defaults to 0.
303
304       "Merge => 0|1"
305            This option is used to compress input data and append it to an
306            existing compressed data stream in $output. The end result is a
307            single compressed data stream stored in $output.
308
309            It is a fatal error to attempt to use this option when $output is
310            not an RFC 1950 data stream.
311
312            There are a number of other limitations with the "Merge" option:
313
314            1.   This module needs to have been built with zlib 1.2.1 or
315                 better to work. A fatal error will be thrown if "Merge" is
316                 used with an older version of zlib.
317
318            2.   If $output is a file or a filehandle, it must be seekable.
319
320            This parameter defaults to 0.
321
322       -Level
323            Defines the compression level used by zlib. The value should
324            either be a number between 0 and 9 (0 means no compression and 9
325            is maximum compression), or one of the symbolic constants defined
326            below.
327
328               Z_NO_COMPRESSION
329               Z_BEST_SPEED
330               Z_BEST_COMPRESSION
331               Z_DEFAULT_COMPRESSION
332
333            The default is Z_DEFAULT_COMPRESSION.
334
335            Note, these constants are not imported by "IO::Compress::Deflate"
336            by default.
337
338                use IO::Compress::Deflate qw(:strategy);
339                use IO::Compress::Deflate qw(:constants);
340                use IO::Compress::Deflate qw(:all);
341
342       -Strategy
343            Defines the strategy used to tune the compression. Use one of the
344            symbolic constants defined below.
345
346               Z_FILTERED
347               Z_HUFFMAN_ONLY
348               Z_RLE
349               Z_FIXED
350               Z_DEFAULT_STRATEGY
351
352            The default is Z_DEFAULT_STRATEGY.
353
354       "Strict => 0|1"
355            This is a placeholder option.
356
357   Examples
358       TODO
359

Methods

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

Importing

546       A number of symbolic constants are required by some methods in
547       "IO::Compress::Deflate". None are imported by default.
548
549       :all Imports "deflate", $DeflateError and all symbolic constants that
550            can be used by "IO::Compress::Deflate". Same as doing this
551
552                use IO::Compress::Deflate qw(deflate $DeflateError :constants) ;
553
554       :constants
555            Import all symbolic constants. Same as doing this
556
557                use IO::Compress::Deflate qw(:flush :level :strategy) ;
558
559       :flush
560            These symbolic constants are used by the "flush" method.
561
562                Z_NO_FLUSH
563                Z_PARTIAL_FLUSH
564                Z_SYNC_FLUSH
565                Z_FULL_FLUSH
566                Z_FINISH
567                Z_BLOCK
568
569       :level
570            These symbolic constants are used by the "Level" option in the
571            constructor.
572
573                Z_NO_COMPRESSION
574                Z_BEST_SPEED
575                Z_BEST_COMPRESSION
576                Z_DEFAULT_COMPRESSION
577
578       :strategy
579            These symbolic constants are used by the "Strategy" option in the
580            constructor.
581
582                Z_FILTERED
583                Z_HUFFMAN_ONLY
584                Z_RLE
585                Z_FIXED
586                Z_DEFAULT_STRATEGY
587

EXAMPLES

589   Apache::GZip Revisited
590       See IO::Compress::FAQ
591
592   Working with Net::FTP
593       See IO::Compress::FAQ
594

AUTHOR

620       This module was written by Paul Marquess, pmqs@cpan.org.
621

MODIFICATION HISTORY

623       See the Changes file.
624

COPYRIGHT AND LICENSE

626       Copyright (c) 2005-2009 Paul Marquess. All rights reserved.
627
628       This program is free software; you can redistribute it and/or modify it
629       under the same terms as Perl itself.
630
631
632
633perl v5.10.1                      2017-03-22        IO::Compress::Deflate(3pm)