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

OO Interface

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

Methods

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

Importing

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

EXAMPLES

641   Apache::GZip Revisited
642       See IO::Compress::FAQ
643
644   Working with Net::FTP
645       See IO::Compress::FAQ
646

AUTHOR

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

MODIFICATION HISTORY

677       See the Changes file.
678

COPYRIGHT AND LICENSE

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