IO::Compress::RawDeflate(3pm)

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

OO Interface

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

Methods

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

Importing

568       A number of symbolic constants are required by some methods in
569       "IO::Compress::RawDeflate". None are imported by default.
570
571       :all Imports "rawdeflate", $RawDeflateError and all symbolic constants
572            that can be used by "IO::Compress::RawDeflate". Same as doing this
573
574                use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError :constants) ;
575
576       :constants
577            Import all symbolic constants. Same as doing this
578
579                use IO::Compress::RawDeflate qw(:flush :level :strategy) ;
580
581       :flush
582            These symbolic constants are used by the "flush" method.
583
584                Z_NO_FLUSH
585                Z_PARTIAL_FLUSH
586                Z_SYNC_FLUSH
587                Z_FULL_FLUSH
588                Z_FINISH
589                Z_BLOCK
590
591       :level
592            These symbolic constants are used by the "Level" option in the
593            constructor.
594
595                Z_NO_COMPRESSION
596                Z_BEST_SPEED
597                Z_BEST_COMPRESSION
598                Z_DEFAULT_COMPRESSION
599
600       :strategy
601            These symbolic constants are used by the "Strategy" option in the
602            constructor.
603
604                Z_FILTERED
605                Z_HUFFMAN_ONLY
606                Z_RLE
607                Z_FIXED
608                Z_DEFAULT_STRATEGY
609
610       For
611

EXAMPLES

613       TODO
614

AUTHOR

639       This module was written by Paul Marquess, pmqs@cpan.org.
640

MODIFICATION HISTORY

642       See the Changes file.
643

COPYRIGHT AND LICENSE

645       Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
646
647       This program is free software; you can redistribute it and/or modify it
648       under the same terms as Perl itself.
649
650
651
652perl v5.8.8                       2007-06-18       IO::Compress::RawDeflate(3)