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
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_filename_or_reference => $output_filename_or_reference [,OPTS]
67               or die "rawdeflate failed: $RawDeflateError\n";
68
69       The functional interface needs Perl5.005 or better.
70
71   rawdeflate $input_filename_or_reference => $output_filename_or_reference [,
72       OPTS]
73       "rawdeflate" expects at least two parameters,
74       $input_filename_or_reference and $output_filename_or_reference.
75
76       The $input_filename_or_reference parameter
77
78       The parameter, $input_filename_or_reference, is used to define the
79       source of the uncompressed data.
80
81       It can take one of the following forms:
82
83       A filename
84            If the <$input_filename_or_reference> parameter is a simple
85            scalar, it is assumed to be a filename. This file will be opened
86            for reading and the input data will be read from it.
87
88       A filehandle
89            If the $input_filename_or_reference parameter is a filehandle, the
90            input data will be read from it.  The string '-' can be used as an
91            alias for standard input.
92
93       A scalar reference
94            If $input_filename_or_reference is a scalar reference, the input
95            data will be read from $$input_filename_or_reference.
96
97       An array reference
98            If $input_filename_or_reference is an array reference, each
99            element in the array must be a filename.
100
101            The input data will be read from each file in turn.
102
103            The complete array will be walked to ensure that it only contains
104            valid filenames before any data is compressed.
105
106       An Input FileGlob string
107            If $input_filename_or_reference is a string that is delimited by
108            the characters "<" and ">" "rawdeflate" will assume that it is an
109            input fileglob string. The input is the list of files that match
110            the fileglob.
111
112            See File::GlobMapper for more details.
113
114       If the $input_filename_or_reference parameter is any other type,
115       "undef" will be returned.
116
117       The $output_filename_or_reference parameter
118
119       The parameter $output_filename_or_reference is used to control the
120       destination of the compressed data. This parameter can take one of
121       these forms.
122
123       A filename
124            If the $output_filename_or_reference parameter is a simple scalar,
125            it is assumed to be a filename.  This file will be opened for
126            writing and the compressed data will be written to it.
127
128       A filehandle
129            If the $output_filename_or_reference parameter is a filehandle,
130            the compressed data will be written to it.  The string '-' can be
131            used as an alias for standard output.
132
133       A scalar reference
134            If $output_filename_or_reference is a scalar reference, the
135            compressed data will be stored in $$output_filename_or_reference.
136
137       An Array Reference
138            If $output_filename_or_reference is an array reference, the
139            compressed data will be pushed onto the array.
140
141       An Output FileGlob
142            If $output_filename_or_reference is a string that is delimited by
143            the characters "<" and ">" "rawdeflate" will assume that it is an
144            output fileglob string. The output is the list of files that match
145            the fileglob.
146
147            When $output_filename_or_reference is an fileglob string,
148            $input_filename_or_reference must also be a fileglob string.
149            Anything else is an error.
150
151            See File::GlobMapper for more details.
152
153       If the $output_filename_or_reference parameter is any other type,
154       "undef" will be returned.
155
156   Notes
157       When $input_filename_or_reference maps to multiple files/buffers and
158       $output_filename_or_reference is a single file/buffer the input
159       files/buffers will be stored in $output_filename_or_reference as a
160       concatenated series of compressed data streams.
161
162   Optional Parameters
163       Unless specified below, the optional parameters for "rawdeflate",
164       "OPTS", are the same as those used with the OO interface defined in the
165       "Constructor Options" section below.
166
167       "AutoClose => 0|1"
168            This option applies to any input or output data streams to
169            "rawdeflate" that are filehandles.
170
171            If "AutoClose" is specified, and the value is true, it will result
172            in all input and/or output filehandles being closed once
173            "rawdeflate" has completed.
174
175            This parameter defaults to 0.
176
177       "BinModeIn => 0|1"
178            This option is now a no-op. All files will be read in binmode.
179
180       "Append => 0|1"
181            The behaviour of this option is dependent on the type of output
182            data stream.
183
184            ·    A Buffer
185
186                 If "Append" is enabled, all compressed data will be append to
187                 the end of the output buffer. Otherwise the output buffer
188                 will be cleared before any compressed data is written to it.
189
190            ·    A Filename
191
192                 If "Append" is enabled, the file will be opened in append
193                 mode. Otherwise the contents of the file, if any, will be
194                 truncated before any compressed data is written to it.
195
196            ·    A Filehandle
197
198                 If "Append" is enabled, the filehandle will be positioned to
199                 the end of the file via a call to "seek" before any
200                 compressed data is written to it.  Otherwise the file pointer
201                 will not be moved.
202
203            When "Append" is specified, and set to true, it will append all
204            compressed data to the output data stream.
205
206            So when the output is a filehandle it will carry out a seek to the
207            eof before writing any compressed data. If the output is a
208            filename, it will be opened for appending. If the output is a
209            buffer, all compressed data will be appended to the existing
210            buffer.
211
212            Conversely when "Append" is not specified, or it is present and is
213            set to false, it will operate as follows.
214
215            When the output is a filename, it will truncate the contents of
216            the file before writing any compressed data. If the output is a
217            filehandle its position will not be changed. If the output is a
218            buffer, it will be wiped before any compressed data is output.
219
220            Defaults to 0.
221
222   Examples
223       To read the contents of the file "file1.txt" and write the compressed
224       data to the file "file1.txt.1951".
225
226           use strict ;
227           use warnings ;
228           use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
229
230           my $input = "file1.txt";
231           rawdeflate $input => "$input.1951"
232               or die "rawdeflate failed: $RawDeflateError\n";
233
234       To read from an existing Perl filehandle, $input, and write the
235       compressed data to a buffer, $buffer.
236
237           use strict ;
238           use warnings ;
239           use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
240           use IO::File ;
241
242           my $input = new IO::File "<file1.txt"
243               or die "Cannot open 'file1.txt': $!\n" ;
244           my $buffer ;
245           rawdeflate $input => \$buffer
246               or die "rawdeflate failed: $RawDeflateError\n";
247
248       To compress all files in the directory "/my/home" that match "*.txt"
249       and store the compressed data in the same directory
250
251           use strict ;
252           use warnings ;
253           use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
254
255           rawdeflate '</my/home/*.txt>' => '<*.1951>'
256               or die "rawdeflate failed: $RawDeflateError\n";
257
258       and if you want to compress each file one at a time, this will do the
259       trick
260
261           use strict ;
262           use warnings ;
263           use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
264
265           for my $input ( glob "/my/home/*.txt" )
266           {
267               my $output = "$input.1951" ;
268               rawdeflate $input => $output
269                   or die "Error compressing '$input': $RawDeflateError\n";
270           }
271

OO Interface

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

Methods

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

Importing

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

EXAMPLES

638   Apache::GZip Revisited
639       See IO::Compress::FAQ
640
641   Working with Net::FTP
642       See IO::Compress::FAQ
643

AUTHOR

673       This module was written by Paul Marquess, "pmqs@cpan.org".
674

MODIFICATION HISTORY

676       See the Changes file.
677

COPYRIGHT AND LICENSE

679       Copyright (c) 2005-2019 Paul Marquess. All rights reserved.
680
681       This program is free software; you can redistribute it and/or modify it
682       under the same terms as Perl itself.
683
684
685
686perl v5.30.0                      2019-08-12       IO::Compress::RawDeflate(3)