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

OO Interface

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

Methods

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

Importing

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

EXAMPLES

628   Apache::GZip Revisited
629       See IO::Compress::FAQ
630
631   Working with Net::FTP
632       See IO::Compress::FAQ
633

AUTHOR

660       This module was written by Paul Marquess, pmqs@cpan.org.
661

MODIFICATION HISTORY

663       See the Changes file.
664

COPYRIGHT AND LICENSE

666       Copyright (c) 2005-2010 Paul Marquess. All rights reserved.
667
668       This program is free software; you can redistribute it and/or modify it
669       under the same terms as Perl itself.
670
671
672
673perl v5.12.4                      2011-06-07        IO::Compress::Deflate(3pm)