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

OO Interface

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

Methods

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

Importing

617       A number of symbolic constants are required by some methods in
618       "IO::Compress::RawDeflate". None are imported by default.
619
620       :all Imports "rawdeflate", $RawDeflateError and all symbolic constants
621            that can be used by "IO::Compress::RawDeflate". Same as doing this
622
623                use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError :constants) ;
624
625       :constants
626            Import all symbolic constants. Same as doing this
627
628                use IO::Compress::RawDeflate qw(:flush :level :strategy) ;
629
630       :flush
631            These symbolic constants are used by the "flush" method.
632
633                Z_NO_FLUSH
634                Z_PARTIAL_FLUSH
635                Z_SYNC_FLUSH
636                Z_FULL_FLUSH
637                Z_FINISH
638                Z_BLOCK
639
640       :level
641            These symbolic constants are used by the "Level" option in the
642            constructor.
643
644                Z_NO_COMPRESSION
645                Z_BEST_SPEED
646                Z_BEST_COMPRESSION
647                Z_DEFAULT_COMPRESSION
648
649       :strategy
650            These symbolic constants are used by the "Strategy" option in the
651            constructor.
652
653                Z_FILTERED
654                Z_HUFFMAN_ONLY
655                Z_RLE
656                Z_FIXED
657                Z_DEFAULT_STRATEGY
658

EXAMPLES

660   Apache::GZip Revisited
661       See IO::Compress::FAQ
662
663   Working with Net::FTP
664       See IO::Compress::FAQ
665

SUPPORT

667       General feedback/questions/bug reports should be sent to
668       <https://github.com/pmqs/IO-Compress/issues> (preferred) or
669       <https://rt.cpan.org/Public/Dist/Display.html?Name=IO-Compress>.
670

AUTHOR

703       This module was written by Paul Marquess, "pmqs@cpan.org".
704

MODIFICATION HISTORY

706       See the Changes file.
707

COPYRIGHT AND LICENSE

709       Copyright (c) 2005-2023 Paul Marquess. All rights reserved.
710
711       This program is free software; you can redistribute it and/or modify it
712       under the same terms as Perl itself.
713
714
715
716perl v5.36.0                      2023-02-09       IO::Compress::RawDeflate(3)