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   Oneshot 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       The constructor takes one mandatory parameter, $output, defined below
303       and zero or more "OPTS", defined in "Constructor Options".
304
305       It returns an "IO::Compress::RawDeflate" object on success and "undef"
306       on failure.  The variable $RawDeflateError will contain an error
307       message on failure.
308
309       If you are running Perl 5.005 or better the object, $z, returned from
310       IO::Compress::RawDeflate can be used exactly like an IO::File
311       filehandle.  This means that all normal output file operations can be
312       carried out with $z.  For example, to write to a compressed file/buffer
313       you can use either of these forms
314
315           $z->print("hello world\n");
316           print $z "hello world\n";
317
318       Below is a simple exaple of using the OO interface to create an output
319       file "myfile.1951" and write some data to it.
320
321           my $filename = "myfile.1951";
322           my $z = IO::Compress::RawDeflate->new($filename)
323               or die "IO::Compress::RawDeflate failed: $RawDeflateError\n";
324
325           $z->print("abcde");
326           $z->close();
327
328       See the "Examples" for more.
329
330       The mandatory parameter $output is used to control the destination of
331       the compressed data. This parameter can take one of these forms.
332
333       A filename
334            If the $output parameter is a simple scalar, it is assumed to be a
335            filename. This file will be opened for writing and the compressed
336            data will be written to it.
337
338       A filehandle
339            If the $output parameter is a filehandle, the compressed data will
340            be written to it.  The string '-' can be used as an alias for
341            standard output.
342
343       A scalar reference
344            If $output is a scalar reference, the compressed data will be
345            stored in $$output.
346
347       If the $output parameter is any other type,
348       "IO::Compress::RawDeflate"::new will return undef.
349
350   Constructor Options
351       "OPTS" is any combination of zero or more the following options:
352
353       "AutoClose => 0|1"
354            This option is only valid when the $output parameter is a
355            filehandle. If specified, and the value is true, it will result in
356            the $output being closed once either the "close" method is called
357            or the "IO::Compress::RawDeflate" object is destroyed.
358
359            This parameter defaults to 0.
360
361       "Append => 0|1"
362            Opens $output in append mode.
363
364            The behaviour of this option is dependent on the type of $output.
365
366            •    A Buffer
367
368                 If $output is a buffer and "Append" is enabled, all
369                 compressed data will be append to the end of $output.
370                 Otherwise $output will be cleared before any data is written
371                 to it.
372
373            •    A Filename
374
375                 If $output is a filename and "Append" is enabled, the file
376                 will be opened in append mode. Otherwise the contents of the
377                 file, if any, will be truncated before any compressed data is
378                 written to it.
379
380            •    A Filehandle
381
382                 If $output is a filehandle, the file pointer will be
383                 positioned to the end of the file via a call to "seek" before
384                 any compressed data is written to it.  Otherwise the file
385                 pointer will not be moved.
386
387            This parameter defaults to 0.
388
389       "Merge => 0|1"
390            This option is used to compress input data and append it to an
391            existing compressed data stream in $output. The end result is a
392            single compressed data stream stored in $output.
393
394            It is a fatal error to attempt to use this option when $output is
395            not an RFC 1951 data stream.
396
397            There are a number of other limitations with the "Merge" option:
398
399            1.   This module needs to have been built with zlib 1.2.1 or
400                 better to work. A fatal error will be thrown if "Merge" is
401                 used with an older version of zlib.
402
403            2.   If $output is a file or a filehandle, it must be seekable.
404
405            This parameter defaults to 0.
406
407       -Level
408            Defines the compression level used by zlib. The value should
409            either be a number between 0 and 9 (0 means no compression and 9
410            is maximum compression), or one of the symbolic constants defined
411            below.
412
413               Z_NO_COMPRESSION
414               Z_BEST_SPEED
415               Z_BEST_COMPRESSION
416               Z_DEFAULT_COMPRESSION
417
418            The default is Z_DEFAULT_COMPRESSION.
419
420            Note, these constants are not imported by
421            "IO::Compress::RawDeflate" by default.
422
423                use IO::Compress::RawDeflate qw(:strategy);
424                use IO::Compress::RawDeflate qw(:constants);
425                use IO::Compress::RawDeflate qw(:all);
426
427       -Strategy
428            Defines the strategy used to tune the compression. Use one of the
429            symbolic constants defined below.
430
431               Z_FILTERED
432               Z_HUFFMAN_ONLY
433               Z_RLE
434               Z_FIXED
435               Z_DEFAULT_STRATEGY
436
437            The default is Z_DEFAULT_STRATEGY.
438
439       "Strict => 0|1"
440            This is a placeholder option.
441
442   Examples
443       Streaming
444
445       This very simple command line example demonstrates the streaming
446       capabilities of the module. The code reads data from STDIN or all the
447       files given on the commandline, compresses it, and writes the
448       compressed data to STDOUT.
449
450           use strict ;
451           use warnings ;
452           use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
453
454           my $z = IO::Compress::RawDeflate->new("-", Stream => 1)
455               or die "IO::Compress::RawDeflate failed: $RawDeflateError\n";
456
457           while (<>) {
458               $z->print("abcde");
459           }
460           $z->close();
461
462       Note the use of "-" to means "STDOUT". Alternatively you can use
463       "\*STDOUT".
464
465       Compressing a file from the filesystem
466
467       To read the contents of the file "file1.txt" and write the compressed
468       data to the file "file1.txt.1951" there are a few options
469
470       Start by creating the compression object and opening the input file
471
472           use strict ;
473           use warnings ;
474           use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
475
476           my $input = "file1.txt";
477           my $z = IO::Compress::RawDeflate->new("file1.txt.1951")
478               or die "IO::Compress::RawDeflate failed: $RawDeflateError\n";
479
480           # open the input file
481           open my $fh, "<", "file1.txt"
482               or die "Cannot open file1.txt: $!\n";
483
484           # loop through the input file & write to the compressed file
485           while (<$fh>) {
486               $z->print($_);
487           }
488
489           # not forgetting to close the compressed file
490           $z->close();
491

Methods

493   print
494       Usage is
495
496           $z->print($data)
497           print $z $data
498
499       Compresses and outputs the contents of the $data parameter. This has
500       the same behaviour as the "print" built-in.
501
502       Returns true if successful.
503
504   printf
505       Usage is
506
507           $z->printf($format, $data)
508           printf $z $format, $data
509
510       Compresses and outputs the contents of the $data parameter.
511
512       Returns true if successful.
513
514   syswrite
515       Usage is
516
517           $z->syswrite $data
518           $z->syswrite $data, $length
519           $z->syswrite $data, $length, $offset
520
521       Compresses and outputs the contents of the $data parameter.
522
523       Returns the number of uncompressed bytes written, or "undef" if
524       unsuccessful.
525
526   write
527       Usage is
528
529           $z->write $data
530           $z->write $data, $length
531           $z->write $data, $length, $offset
532
533       Compresses and outputs the contents of the $data parameter.
534
535       Returns the number of uncompressed bytes written, or "undef" if
536       unsuccessful.
537
538   flush
539       Usage is
540
541           $z->flush;
542           $z->flush($flush_type);
543
544       Flushes any pending compressed data to the output file/buffer.
545
546       This method takes an optional parameter, $flush_type, that controls how
547       the flushing will be carried out. By default the $flush_type used is
548       "Z_FINISH". Other valid values for $flush_type are "Z_NO_FLUSH",
549       "Z_SYNC_FLUSH", "Z_FULL_FLUSH" and "Z_BLOCK". It is strongly
550       recommended that you only set the "flush_type" parameter if you fully
551       understand the implications of what it does - overuse of "flush" can
552       seriously degrade the level of compression achieved. See the "zlib"
553       documentation for details.
554
555       Returns true on success.
556
557   tell
558       Usage is
559
560           $z->tell()
561           tell $z
562
563       Returns the uncompressed file offset.
564
565   eof
566       Usage is
567
568           $z->eof();
569           eof($z);
570
571       Returns true if the "close" method has been called.
572
573   seek
574           $z->seek($position, $whence);
575           seek($z, $position, $whence);
576
577       Provides a sub-set of the "seek" functionality, with the restriction
578       that it is only legal to seek forward in the output file/buffer.  It is
579       a fatal error to attempt to seek backward.
580
581       Empty parts of the file/buffer will have NULL (0x00) bytes written to
582       them.
583
584       The $whence parameter takes one the usual values, namely SEEK_SET,
585       SEEK_CUR or SEEK_END.
586
587       Returns 1 on success, 0 on failure.
588
589   binmode
590       Usage is
591
592           $z->binmode
593           binmode $z ;
594
595       This is a noop provided for completeness.
596
597   opened
598           $z->opened()
599
600       Returns true if the object currently refers to a opened file/buffer.
601
602   autoflush
603           my $prev = $z->autoflush()
604           my $prev = $z->autoflush(EXPR)
605
606       If the $z object is associated with a file or a filehandle, this method
607       returns the current autoflush setting for the underlying filehandle. If
608       "EXPR" is present, and is non-zero, it will enable flushing after every
609       write/print operation.
610
611       If $z is associated with a buffer, this method has no effect and always
612       returns "undef".
613
614       Note that the special variable $| cannot be used to set or retrieve the
615       autoflush setting.
616
617   input_line_number
618           $z->input_line_number()
619           $z->input_line_number(EXPR)
620
621       This method always returns "undef" when compressing.
622
623   fileno
624           $z->fileno()
625           fileno($z)
626
627       If the $z object is associated with a file or a filehandle, "fileno"
628       will return the underlying file descriptor. Once the "close" method is
629       called "fileno" will return "undef".
630
631       If the $z object is associated with a buffer, this method will return
632       "undef".
633
634   close
635           $z->close() ;
636           close $z ;
637
638       Flushes any pending compressed data and then closes the output
639       file/buffer.
640
641       For most versions of Perl this method will be automatically invoked if
642       the IO::Compress::RawDeflate object is destroyed (either explicitly or
643       by the variable with the reference to the object going out of scope).
644       The exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
645       these cases, the "close" method will be called automatically, but not
646       until global destruction of all live objects when the program is
647       terminating.
648
649       Therefore, if you want your scripts to be able to run on all versions
650       of Perl, you should call "close" explicitly and not rely on automatic
651       closing.
652
653       Returns true on success, otherwise 0.
654
655       If the "AutoClose" option has been enabled when the
656       IO::Compress::RawDeflate object was created, and the object is
657       associated with a file, the underlying file will also be closed.
658
659   newStream([OPTS])
660       Usage is
661
662           $z->newStream( [OPTS] )
663
664       Closes the current compressed data stream and starts a new one.
665
666       OPTS consists of any of the options that are available when creating
667       the $z object.
668
669       See the "Constructor Options" section for more details.
670
671   deflateParams
672       Usage is
673
674           $z->deflateParams
675
676       TODO
677

Importing

679       A number of symbolic constants are required by some methods in
680       "IO::Compress::RawDeflate". None are imported by default.
681
682       :all Imports "rawdeflate", $RawDeflateError and all symbolic constants
683            that can be used by "IO::Compress::RawDeflate". Same as doing this
684
685                use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError :constants) ;
686
687       :constants
688            Import all symbolic constants. Same as doing this
689
690                use IO::Compress::RawDeflate qw(:flush :level :strategy) ;
691
692       :flush
693            These symbolic constants are used by the "flush" method.
694
695                Z_NO_FLUSH
696                Z_PARTIAL_FLUSH
697                Z_SYNC_FLUSH
698                Z_FULL_FLUSH
699                Z_FINISH
700                Z_BLOCK
701
702       :level
703            These symbolic constants are used by the "Level" option in the
704            constructor.
705
706                Z_NO_COMPRESSION
707                Z_BEST_SPEED
708                Z_BEST_COMPRESSION
709                Z_DEFAULT_COMPRESSION
710
711       :strategy
712            These symbolic constants are used by the "Strategy" option in the
713            constructor.
714
715                Z_FILTERED
716                Z_HUFFMAN_ONLY
717                Z_RLE
718                Z_FIXED
719                Z_DEFAULT_STRATEGY
720

EXAMPLES

722   Apache::GZip Revisited
723       See IO::Compress::FAQ
724
725   Working with Net::FTP
726       See IO::Compress::FAQ
727

SUPPORT

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

AUTHOR

765       This module was written by Paul Marquess, "pmqs@cpan.org".
766

MODIFICATION HISTORY

768       See the Changes file.
769

COPYRIGHT AND LICENSE

771       Copyright (c) 2005-2023 Paul Marquess. All rights reserved.
772
773       This program is free software; you can redistribute it and/or modify it
774       under the same terms as Perl itself.
775
776
777
778perl v5.38.0                      2023-07-26       IO::Compress::RawDeflate(3)