IO::Compress::RawDeflate(3pm)

1IO::Compress::RawDeflateP(e3rplm)Programmers ReferenceIGOu:i:dCeompress::RawDeflate(3pm)
2
3
4

NAME

6       IO::Compress::RawDeflate - Write RFC 1951 files/buffers
7

SYNOPSIS

9           use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
10
11           my $status = rawdeflate $input => $output [,OPTS]
12               or die "rawdeflate failed: $RawDeflateError\n";
13
14           my $z = new IO::Compress::RawDeflate $output [,OPTS]
15               or die "rawdeflate failed: $RawDeflateError\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           $RawDeflateError ;
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 1951.
52
53       Note that RFC 1951 data is not a good choice of compression format to
54       use in isolation, especially if you want to auto-detect it.
55
56       For reading RFC 1951 files/buffers, see the companion module
57       IO::Uncompress::RawInflate.
58

Functional Interface

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

OO Interface

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

Methods

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

Importing

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

EXAMPLES

593   Apache::GZip Revisited
594       See IO::Compress::FAQ
595
596   Working with Net::FTP
597       See IO::Compress::FAQ
598

AUTHOR

624       This module was written by Paul Marquess, pmqs@cpan.org.
625

MODIFICATION HISTORY

627       See the Changes file.
628

COPYRIGHT AND LICENSE

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