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

OO Interface

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

Methods

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

Importing

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

EXAMPLES

632   Apache::GZip Revisited
633       See IO::Compress::FAQ
634
635   Working with Net::FTP
636       See IO::Compress::FAQ
637

AUTHOR

664       This module was written by Paul Marquess, pmqs@cpan.org.
665

MODIFICATION HISTORY

667       See the Changes file.
668

COPYRIGHT AND LICENSE

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