Debian Codegraph @

upstream/debian-unstable/man3/IO::Compress::RawDeflate.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "IO::Compress::RawDeflate 3perl"
58 .TH IO::Compress::RawDeflate 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 IO::Compress::RawDeflate \- Write RFC 1951 files/buffers
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
69 \&
70 \& my $status = rawdeflate $input => $output [,OPTS]
71 \& or die "rawdeflate failed: $RawDeflateError\en";
72 \&
73 \& my $z = IO::Compress::RawDeflate\->new( $output [,OPTS] )
74 \& or die "rawdeflate failed: $RawDeflateError\en";
75 \&
76 \& $z\->print($string);
77 \& $z\->printf($format, $string);
78 \& $z\->write($string);
79 \& $z\->syswrite($string [, $length, $offset]);
80 \& $z\->flush();
81 \& $z\->tell();
82 \& $z\->eof();
83 \& $z\->seek($position, $whence);
84 \& $z\->binmode();
85 \& $z\->fileno();
86 \& $z\->opened();
87 \& $z\->autoflush();
88 \& $z\->input_line_number();
89 \& $z\->newStream( [OPTS] );
90 \&
91 \& $z\->deflateParams();
92 \&
93 \& $z\->close() ;
94 \&
95 \& $RawDeflateError ;
96 \&
97 \& # IO::File mode
98 \&
99 \& print $z $string;
100 \& printf $z $format, $string;
101 \& tell $z
102 \& eof $z
103 \& seek $z, $position, $whence
104 \& binmode $z
105 \& fileno $z
106 \& close $z ;
107 .Ve
108 .SH DESCRIPTION
109 .IX Header "DESCRIPTION"
110 This module provides a Perl interface that allows writing compressed
111 data to files or buffer as defined in RFC 1951.
112 .PP
113 Note that RFC 1951 data is not a good choice of compression format
114 to use in isolation, especially if you want to auto-detect it.
115 .PP
116 For reading RFC 1951 files/buffers, see the companion module
117 IO::Uncompress::RawInflate.
118 .SH "Functional Interface"
119 .IX Header "Functional Interface"
120 A top-level function, \f(CW\*(C`rawdeflate\*(C'\fR, is provided to carry out
121 "one-shot" compression between buffers and/or files. For finer
122 control over the compression process, see the "OO Interface"
123 section.
124 .PP
125 .Vb 1
126 \& use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
127 \&
128 \& rawdeflate $input_filename_or_reference => $output_filename_or_reference [,OPTS]
129 \& or die "rawdeflate failed: $RawDeflateError\en";
130 .Ve
131 .PP
132 The functional interface needs Perl5.005 or better.
133 .ie n .SS "rawdeflate $input_filename_or_reference => $output_filename_or_reference [, OPTS]"
134 .el .SS "rawdeflate \f(CW$input_filename_or_reference\fP => \f(CW$output_filename_or_reference\fP [, OPTS]"
135 .IX Subsection "rawdeflate $input_filename_or_reference => $output_filename_or_reference [, OPTS]"
136 \&\f(CW\*(C`rawdeflate\*(C'\fR expects at least two parameters,
137 \&\f(CW$input_filename_or_reference\fR and \f(CW$output_filename_or_reference\fR
138 and zero or more optional parameters (see "Optional Parameters")
139 .PP
140 \fIThe \fR\f(CI$input_filename_or_reference\fR\fI parameter\fR
141 .IX Subsection "The $input_filename_or_reference parameter"
142 .PP
143 The parameter, \f(CW$input_filename_or_reference\fR, is used to define the
144 source of the uncompressed data.
145 .PP
146 It can take one of the following forms:
147 .IP "A filename" 5
148 .IX Item "A filename"
149 If the \f(CW$input_filename_or_reference\fR parameter is a simple scalar, it is
150 assumed to be a filename. This file will be opened for reading and the
151 input data will be read from it.
152 .IP "A filehandle" 5
153 .IX Item "A filehandle"
154 If the \f(CW$input_filename_or_reference\fR parameter is a filehandle, the input
155 data will be read from it. The string '\-' can be used as an alias for
156 standard input.
157 .IP "A scalar reference" 5
158 .IX Item "A scalar reference"
159 If \f(CW$input_filename_or_reference\fR is a scalar reference, the input data
160 will be read from \f(CW$$input_filename_or_reference\fR.
161 .IP "An array reference" 5
162 .IX Item "An array reference"
163 If \f(CW$input_filename_or_reference\fR is an array reference, each element in
164 the array must be a filename.
165 .Sp
166 The input data will be read from each file in turn.
167 .Sp
168 The complete array will be walked to ensure that it only
169 contains valid filenames before any data is compressed.
170 .IP "An Input FileGlob string" 5
171 .IX Item "An Input FileGlob string"
172 If \f(CW$input_filename_or_reference\fR is a string that is delimited by the
173 characters "<" and ">" \f(CW\*(C`rawdeflate\*(C'\fR will assume that it is an
174 \&\fIinput fileglob string\fR. The input is the list of files that match the
175 fileglob.
176 .Sp
177 See File::GlobMapper for more details.
178 .PP
179 If the \f(CW$input_filename_or_reference\fR parameter is any other type,
180 \&\f(CW\*(C`undef\*(C'\fR will be returned.
181 .PP
182 \fIThe \fR\f(CI$output_filename_or_reference\fR\fI parameter\fR
183 .IX Subsection "The $output_filename_or_reference parameter"
184 .PP
185 The parameter \f(CW$output_filename_or_reference\fR is used to control the
186 destination of the compressed data. This parameter can take one of
187 these forms.
188 .IP "A filename" 5
189 .IX Item "A filename"
190 If the \f(CW$output_filename_or_reference\fR parameter is a simple scalar, it is
191 assumed to be a filename. This file will be opened for writing and the
192 compressed data will be written to it.
193 .IP "A filehandle" 5
194 .IX Item "A filehandle"
195 If the \f(CW$output_filename_or_reference\fR parameter is a filehandle, the
196 compressed data will be written to it. The string '\-' can be used as
197 an alias for standard output.
198 .IP "A scalar reference" 5
199 .IX Item "A scalar reference"
200 If \f(CW$output_filename_or_reference\fR is a scalar reference, the
201 compressed data will be stored in \f(CW$$output_filename_or_reference\fR.
202 .IP "An Array Reference" 5
203 .IX Item "An Array Reference"
204 If \f(CW$output_filename_or_reference\fR is an array reference,
205 the compressed data will be pushed onto the array.
206 .IP "An Output FileGlob" 5
207 .IX Item "An Output FileGlob"
208 If \f(CW$output_filename_or_reference\fR is a string that is delimited by the
209 characters "<" and ">" \f(CW\*(C`rawdeflate\*(C'\fR will assume that it is an
210 \&\fIoutput fileglob string\fR. The output is the list of files that match the
211 fileglob.
212 .Sp
213 When \f(CW$output_filename_or_reference\fR is an fileglob string,
214 \&\f(CW$input_filename_or_reference\fR must also be a fileglob string. Anything
215 else is an error.
216 .Sp
217 See File::GlobMapper for more details.
218 .PP
219 If the \f(CW$output_filename_or_reference\fR parameter is any other type,
220 \&\f(CW\*(C`undef\*(C'\fR will be returned.
221 .SS Notes
222 .IX Subsection "Notes"
223 When \f(CW$input_filename_or_reference\fR maps to multiple files/buffers and
224 \&\f(CW$output_filename_or_reference\fR is a single
225 file/buffer the input files/buffers will be stored
226 in \f(CW$output_filename_or_reference\fR as a concatenated series of compressed data streams.
227 .SS "Optional Parameters"
228 .IX Subsection "Optional Parameters"
229 The optional parameters for the one-shot function \f(CW\*(C`rawdeflate\*(C'\fR
230 are (for the most part) identical to those used with the OO interface defined in the
231 "Constructor Options" section. The exceptions are listed below
232 .ie n .IP """AutoClose => 0|1""" 5
233 .el .IP "\f(CWAutoClose => 0|1\fR" 5
234 .IX Item "AutoClose => 0|1"
235 This option applies to any input or output data streams to
236 \&\f(CW\*(C`rawdeflate\*(C'\fR that are filehandles.
237 .Sp
238 If \f(CW\*(C`AutoClose\*(C'\fR is specified, and the value is true, it will result in all
239 input and/or output filehandles being closed once \f(CW\*(C`rawdeflate\*(C'\fR has
240 completed.
241 .Sp
242 This parameter defaults to 0.
243 .ie n .IP """BinModeIn => 0|1""" 5
244 .el .IP "\f(CWBinModeIn => 0|1\fR" 5
245 .IX Item "BinModeIn => 0|1"
246 This option is now a no-op. All files will be read in binmode.
247 .ie n .IP """Append => 0|1""" 5
248 .el .IP "\f(CWAppend => 0|1\fR" 5
249 .IX Item "Append => 0|1"
250 The behaviour of this option is dependent on the type of output data
251 stream.
252 .RS 5
253 .IP \(bu 5
254 A Buffer
255 .Sp
256 If \f(CW\*(C`Append\*(C'\fR is enabled, all compressed data will be append to the end of
257 the output buffer. Otherwise the output buffer will be cleared before any
258 compressed data is written to it.
259 .IP \(bu 5
260 A Filename
261 .Sp
262 If \f(CW\*(C`Append\*(C'\fR is enabled, the file will be opened in append mode. Otherwise
263 the contents of the file, if any, will be truncated before any compressed
264 data is written to it.
265 .IP \(bu 5
266 A Filehandle
267 .Sp
268 If \f(CW\*(C`Append\*(C'\fR is enabled, the filehandle will be positioned to the end of
269 the file via a call to \f(CW\*(C`seek\*(C'\fR before any compressed data is
270 written to it. Otherwise the file pointer will not be moved.
271 .RE
272 .RS 5
273 .Sp
274 When \f(CW\*(C`Append\*(C'\fR is specified, and set to true, it will \fIappend\fR all compressed
275 data to the output data stream.
276 .Sp
277 So when the output is a filehandle it will carry out a seek to the eof
278 before writing any compressed data. If the output is a filename, it will be opened for
279 appending. If the output is a buffer, all compressed data will be
280 appended to the existing buffer.
281 .Sp
282 Conversely when \f(CW\*(C`Append\*(C'\fR is not specified, or it is present and is set to
283 false, it will operate as follows.
284 .Sp
285 When the output is a filename, it will truncate the contents of the file
286 before writing any compressed data. If the output is a filehandle
287 its position will not be changed. If the output is a buffer, it will be
288 wiped before any compressed data is output.
289 .Sp
290 Defaults to 0.
291 .RE
292 .SS "Oneshot Examples"
293 .IX Subsection "Oneshot Examples"
294 Here are a few example that show the capabilities of the module.
295 .PP
296 \fIStreaming\fR
297 .IX Subsection "Streaming"
298 .PP
299 This very simple command line example demonstrates the streaming capabilities of the module.
300 The code reads data from STDIN, compresses it, and writes the compressed data to STDOUT.
301 .PP
302 .Vb 1
303 \& $ echo hello world | perl \-MIO::Compress::RawDeflate=rawdeflate \-e \*(Aqrawdeflate \e*STDIN => \e*STDOUT\*(Aq >output.1951
304 .Ve
305 .PP
306 The special filename "\-" can be used as a standin for both \f(CW\*(C`\e*STDIN\*(C'\fR and \f(CW\*(C`\e*STDOUT\*(C'\fR,
307 so the above can be rewritten as
308 .PP
309 .Vb 1
310 \& $ echo hello world | perl \-MIO::Compress::RawDeflate=rawdeflate \-e \*(Aqrawdeflate "\-" => "\-"\*(Aq >output.1951
311 .Ve
312 .PP
313 \fICompressing a file from the filesystem\fR
314 .IX Subsection "Compressing a file from the filesystem"
315 .PP
316 To read the contents of the file \f(CW\*(C`file1.txt\*(C'\fR and write the compressed
317 data to the file \f(CW\*(C`file1.txt.1951\*(C'\fR.
318 .PP
319 .Vb 3
320 \& use strict ;
321 \& use warnings ;
322 \& use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
323 \&
324 \& my $input = "file1.txt";
325 \& rawdeflate $input => "$input.1951"
326 \& or die "rawdeflate failed: $RawDeflateError\en";
327 .Ve
328 .PP
329 \fIReading from a Filehandle and writing to an in-memory buffer\fR
330 .IX Subsection "Reading from a Filehandle and writing to an in-memory buffer"
331 .PP
332 To read from an existing Perl filehandle, \f(CW$input\fR, and write the
333 compressed data to a buffer, \f(CW$buffer\fR.
334 .PP
335 .Vb 4
336 \& use strict ;
337 \& use warnings ;
338 \& use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
339 \& use IO::File ;
340 \&
341 \& my $input = IO::File\->new( "<file1.txt" )
342 \& or die "Cannot open \*(Aqfile1.txt\*(Aq: $!\en" ;
343 \& my $buffer ;
344 \& rawdeflate $input => \e$buffer
345 \& or die "rawdeflate failed: $RawDeflateError\en";
346 .Ve
347 .PP
348 \fICompressing multiple files\fR
349 .IX Subsection "Compressing multiple files"
350 .PP
351 To compress all files in the directory "/my/home" that match "*.txt"
352 and store the compressed data in the same directory
353 .PP
354 .Vb 3
355 \& use strict ;
356 \& use warnings ;
357 \& use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
358 \&
359 \& rawdeflate \*(Aq</my/home/*.txt>\*(Aq => \*(Aq<*.1951>\*(Aq
360 \& or die "rawdeflate failed: $RawDeflateError\en";
361 .Ve
362 .PP
363 and if you want to compress each file one at a time, this will do the trick
364 .PP
365 .Vb 3
366 \& use strict ;
367 \& use warnings ;
368 \& use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
369 \&
370 \& for my $input ( glob "/my/home/*.txt" )
371 \& {
372 \& my $output = "$input.1951" ;
373 \& rawdeflate $input => $output
374 \& or die "Error compressing \*(Aq$input\*(Aq: $RawDeflateError\en";
375 \& }
376 .Ve
377 .SH "OO Interface"
378 .IX Header "OO Interface"
379 .SS Constructor
380 .IX Subsection "Constructor"
381 The format of the constructor for \f(CW\*(C`IO::Compress::RawDeflate\*(C'\fR is shown below
382 .PP
383 .Vb 2
384 \& my $z = IO::Compress::RawDeflate\->new( $output [,OPTS] )
385 \& or die "IO::Compress::RawDeflate failed: $RawDeflateError\en";
386 .Ve
387 .PP
388 The constructor takes one mandatory parameter, \f(CW$output\fR, defined below and
389 zero or more \f(CW\*(C`OPTS\*(C'\fR, defined in "Constructor Options".
390 .PP
391 It returns an \f(CW\*(C`IO::Compress::RawDeflate\*(C'\fR object on success and \f(CW\*(C`undef\*(C'\fR on failure.
392 The variable \f(CW$RawDeflateError\fR will contain an error message on failure.
393 .PP
394 If you are running Perl 5.005 or better the object, \f(CW$z\fR, returned from
395 IO::Compress::RawDeflate can be used exactly like an IO::File filehandle.
396 This means that all normal output file operations can be carried out
397 with \f(CW$z\fR.
398 For example, to write to a compressed file/buffer you can use either of
399 these forms
400 .PP
401 .Vb 2
402 \& $z\->print("hello world\en");
403 \& print $z "hello world\en";
404 .Ve
405 .PP
406 Below is a simple exaple of using the OO interface to create an output file
407 \&\f(CW\*(C`myfile.1951\*(C'\fR and write some data to it.
408 .PP
409 .Vb 3
410 \& my $filename = "myfile.1951";
411 \& my $z = IO::Compress::RawDeflate\->new($filename)
412 \& or die "IO::Compress::RawDeflate failed: $RawDeflateError\en";
413 \&
414 \& $z\->print("abcde");
415 \& $z\->close();
416 .Ve
417 .PP
418 See the "Examples" for more.
419 .PP
420 The mandatory parameter \f(CW$output\fR is used to control the destination
421 of the compressed data. This parameter can take one of these forms.
422 .IP "A filename" 5
423 .IX Item "A filename"
424 If the \f(CW$output\fR parameter is a simple scalar, it is assumed to be a
425 filename. This file will be opened for writing and the compressed data
426 will be written to it.
427 .IP "A filehandle" 5
428 .IX Item "A filehandle"
429 If the \f(CW$output\fR parameter is a filehandle, the compressed data will be
430 written to it.
431 The string '\-' can be used as an alias for standard output.
432 .IP "A scalar reference" 5
433 .IX Item "A scalar reference"
434 If \f(CW$output\fR is a scalar reference, the compressed data will be stored
435 in \f(CW$$output\fR.
436 .PP
437 If the \f(CW$output\fR parameter is any other type, \f(CW\*(C`IO::Compress::RawDeflate\*(C'\fR::new will
438 return undef.
439 .SS "Constructor Options"
440 .IX Subsection "Constructor Options"
441 \&\f(CW\*(C`OPTS\*(C'\fR is any combination of zero or more the following options:
442 .ie n .IP """AutoClose => 0|1""" 5
443 .el .IP "\f(CWAutoClose => 0|1\fR" 5
444 .IX Item "AutoClose => 0|1"
445 This option is only valid when the \f(CW$output\fR parameter is a filehandle. If
446 specified, and the value is true, it will result in the \f(CW$output\fR being
447 closed once either the \f(CW\*(C`close\*(C'\fR method is called or the \f(CW\*(C`IO::Compress::RawDeflate\*(C'\fR
448 object is destroyed.
449 .Sp
450 This parameter defaults to 0.
451 .ie n .IP """Append => 0|1""" 5
452 .el .IP "\f(CWAppend => 0|1\fR" 5
453 .IX Item "Append => 0|1"
454 Opens \f(CW$output\fR in append mode.
455 .Sp
456 The behaviour of this option is dependent on the type of \f(CW$output\fR.
457 .RS 5
458 .IP \(bu 5
459 A Buffer
460 .Sp
461 If \f(CW$output\fR is a buffer and \f(CW\*(C`Append\*(C'\fR is enabled, all compressed data
462 will be append to the end of \f(CW$output\fR. Otherwise \f(CW$output\fR will be
463 cleared before any data is written to it.
464 .IP \(bu 5
465 A Filename
466 .Sp
467 If \f(CW$output\fR is a filename and \f(CW\*(C`Append\*(C'\fR is enabled, the file will be
468 opened in append mode. Otherwise the contents of the file, if any, will be
469 truncated before any compressed data is written to it.
470 .IP \(bu 5
471 A Filehandle
472 .Sp
473 If \f(CW$output\fR is a filehandle, the file pointer will be positioned to the
474 end of the file via a call to \f(CW\*(C`seek\*(C'\fR before any compressed data is written
475 to it. Otherwise the file pointer will not be moved.
476 .RE
477 .RS 5
478 .Sp
479 This parameter defaults to 0.
480 .RE
481 .ie n .IP """Merge => 0|1""" 5
482 .el .IP "\f(CWMerge => 0|1\fR" 5
483 .IX Item "Merge => 0|1"
484 This option is used to compress input data and append it to an existing
485 compressed data stream in \f(CW$output\fR. The end result is a single compressed
486 data stream stored in \f(CW$output\fR.
487 .Sp
488 It is a fatal error to attempt to use this option when \f(CW$output\fR is not an
489 RFC 1951 data stream.
490 .Sp
491 There are a number of other limitations with the \f(CW\*(C`Merge\*(C'\fR option:
492 .RS 5
493 .IP 1. 5
494 This module needs to have been built with zlib 1.2.1 or better to work. A
495 fatal error will be thrown if \f(CW\*(C`Merge\*(C'\fR is used with an older version of
496 zlib.
497 .IP 2. 5
498 If \f(CW$output\fR is a file or a filehandle, it must be seekable.
499 .RE
500 .RS 5
501 .Sp
502 This parameter defaults to 0.
503 .RE
504 .IP \-Level 5
505 .IX Item "-Level"
506 Defines the compression level used by zlib. The value should either be
507 a number between 0 and 9 (0 means no compression and 9 is maximum
508 compression), or one of the symbolic constants defined below.
509 .Sp
510 .Vb 4
511 \& Z_NO_COMPRESSION
512 \& Z_BEST_SPEED
513 \& Z_BEST_COMPRESSION
514 \& Z_DEFAULT_COMPRESSION
515 .Ve
516 .Sp
517 The default is Z_DEFAULT_COMPRESSION.
518 .Sp
519 Note, these constants are not imported by \f(CW\*(C`IO::Compress::RawDeflate\*(C'\fR by default.
520 .Sp
521 .Vb 3
522 \& use IO::Compress::RawDeflate qw(:strategy);
523 \& use IO::Compress::RawDeflate qw(:constants);
524 \& use IO::Compress::RawDeflate qw(:all);
525 .Ve
526 .IP \-Strategy 5
527 .IX Item "-Strategy"
528 Defines the strategy used to tune the compression. Use one of the symbolic
529 constants defined below.
530 .Sp
531 .Vb 5
532 \& Z_FILTERED
533 \& Z_HUFFMAN_ONLY
534 \& Z_RLE
535 \& Z_FIXED
536 \& Z_DEFAULT_STRATEGY
537 .Ve
538 .Sp
539 The default is Z_DEFAULT_STRATEGY.
540 .ie n .IP """Strict => 0|1""" 5
541 .el .IP "\f(CWStrict => 0|1\fR" 5
542 .IX Item "Strict => 0|1"
543 This is a placeholder option.
544 .SS Examples
545 .IX Subsection "Examples"
546 \fIStreaming\fR
547 .IX Subsection "Streaming"
548 .PP
549 This very simple command line example demonstrates the streaming capabilities
550 of the module. The code reads data from STDIN or all the files given on the
551 commandline, compresses it, and writes the compressed data to STDOUT.
552 .PP
553 .Vb 3
554 \& use strict ;
555 \& use warnings ;
556 \& use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
557 \&
558 \& my $z = IO::Compress::RawDeflate\->new("\-", Stream => 1)
559 \& or die "IO::Compress::RawDeflate failed: $RawDeflateError\en";
560 \&
561 \& while (<>) {
562 \& $z\->print("abcde");
563 \& }
564 \& $z\->close();
565 .Ve
566 .PP
567 Note the use of \f(CW"\-"\fR to means \f(CW\*(C`STDOUT\*(C'\fR. Alternatively you can use \f(CW\*(C`\e*STDOUT\*(C'\fR.
568 .PP
569 \fICompressing a file from the filesystem\fR
570 .IX Subsection "Compressing a file from the filesystem"
571 .PP
572 To read the contents of the file \f(CW\*(C`file1.txt\*(C'\fR and write the compressed
573 data to the file \f(CW\*(C`file1.txt.1951\*(C'\fR there are a few options
574 .PP
575 Start by creating the compression object and opening the input file
576 .PP
577 .Vb 3
578 \& use strict ;
579 \& use warnings ;
580 \& use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError) ;
581 \&
582 \& my $input = "file1.txt";
583 \& my $z = IO::Compress::RawDeflate\->new("file1.txt.1951")
584 \& or die "IO::Compress::RawDeflate failed: $RawDeflateError\en";
585 \&
586 \& # open the input file
587 \& open my $fh, "<", "file1.txt"
588 \& or die "Cannot open file1.txt: $!\en";
589 \&
590 \& # loop through the input file & write to the compressed file
591 \& while (<$fh>) {
592 \& $z\->print($_);
593 \& }
594 \&
595 \& # not forgetting to close the compressed file
596 \& $z\->close();
597 .Ve
598 .SH Methods
599 .IX Header "Methods"
600 .SS print
601 .IX Subsection "print"
602 Usage is
603 .PP
604 .Vb 2
605 \& $z\->print($data)
606 \& print $z $data
607 .Ve
608 .PP
609 Compresses and outputs the contents of the \f(CW$data\fR parameter. This
610 has the same behaviour as the \f(CW\*(C`print\*(C'\fR built-in.
611 .PP
612 Returns true if successful.
613 .SS printf
614 .IX Subsection "printf"
615 Usage is
616 .PP
617 .Vb 2
618 \& $z\->printf($format, $data)
619 \& printf $z $format, $data
620 .Ve
621 .PP
622 Compresses and outputs the contents of the \f(CW$data\fR parameter.
623 .PP
624 Returns true if successful.
625 .SS syswrite
626 .IX Subsection "syswrite"
627 Usage is
628 .PP
629 .Vb 3
630 \& $z\->syswrite $data
631 \& $z\->syswrite $data, $length
632 \& $z\->syswrite $data, $length, $offset
633 .Ve
634 .PP
635 Compresses and outputs the contents of the \f(CW$data\fR parameter.
636 .PP
637 Returns the number of uncompressed bytes written, or \f(CW\*(C`undef\*(C'\fR if
638 unsuccessful.
639 .SS write
640 .IX Subsection "write"
641 Usage is
642 .PP
643 .Vb 3
644 \& $z\->write $data
645 \& $z\->write $data, $length
646 \& $z\->write $data, $length, $offset
647 .Ve
648 .PP
649 Compresses and outputs the contents of the \f(CW$data\fR parameter.
650 .PP
651 Returns the number of uncompressed bytes written, or \f(CW\*(C`undef\*(C'\fR if
652 unsuccessful.
653 .SS flush
654 .IX Subsection "flush"
655 Usage is
656 .PP
657 .Vb 2
658 \& $z\->flush;
659 \& $z\->flush($flush_type);
660 .Ve
661 .PP
662 Flushes any pending compressed data to the output file/buffer.
663 .PP
664 This method takes an optional parameter, \f(CW$flush_type\fR, that controls
665 how the flushing will be carried out. By default the \f(CW$flush_type\fR
666 used is \f(CW\*(C`Z_FINISH\*(C'\fR. Other valid values for \f(CW$flush_type\fR are
667 \&\f(CW\*(C`Z_NO_FLUSH\*(C'\fR, \f(CW\*(C`Z_SYNC_FLUSH\*(C'\fR, \f(CW\*(C`Z_FULL_FLUSH\*(C'\fR and \f(CW\*(C`Z_BLOCK\*(C'\fR. It is
668 strongly recommended that you only set the \f(CW\*(C`flush_type\*(C'\fR parameter if
669 you fully understand the implications of what it does \- overuse of \f(CW\*(C`flush\*(C'\fR
670 can seriously degrade the level of compression achieved. See the \f(CW\*(C`zlib\*(C'\fR
671 documentation for details.
672 .PP
673 Returns true on success.
674 .SS tell
675 .IX Subsection "tell"
676 Usage is
677 .PP
678 .Vb 2
679 \& $z\->tell()
680 \& tell $z
681 .Ve
682 .PP
683 Returns the uncompressed file offset.
684 .SS eof
685 .IX Subsection "eof"
686 Usage is
687 .PP
688 .Vb 2
689 \& $z\->eof();
690 \& eof($z);
691 .Ve
692 .PP
693 Returns true if the \f(CW\*(C`close\*(C'\fR method has been called.
694 .SS seek
695 .IX Subsection "seek"
696 .Vb 2
697 \& $z\->seek($position, $whence);
698 \& seek($z, $position, $whence);
699 .Ve
700 .PP
701 Provides a sub-set of the \f(CW\*(C`seek\*(C'\fR functionality, with the restriction
702 that it is only legal to seek forward in the output file/buffer.
703 It is a fatal error to attempt to seek backward.
704 .PP
705 Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
706 .PP
707 The \f(CW$whence\fR parameter takes one the usual values, namely SEEK_SET,
708 SEEK_CUR or SEEK_END.
709 .PP
710 Returns 1 on success, 0 on failure.
711 .SS binmode
712 .IX Subsection "binmode"
713 Usage is
714 .PP
715 .Vb 2
716 \& $z\->binmode
717 \& binmode $z ;
718 .Ve
719 .PP
720 This is a noop provided for completeness.
721 .SS opened
722 .IX Subsection "opened"
723 .Vb 1
724 \& $z\->opened()
725 .Ve
726 .PP
727 Returns true if the object currently refers to a opened file/buffer.
728 .SS autoflush
729 .IX Subsection "autoflush"
730 .Vb 2
731 \& my $prev = $z\->autoflush()
732 \& my $prev = $z\->autoflush(EXPR)
733 .Ve
734 .PP
735 If the \f(CW$z\fR object is associated with a file or a filehandle, this method
736 returns the current autoflush setting for the underlying filehandle. If
737 \&\f(CW\*(C`EXPR\*(C'\fR is present, and is non-zero, it will enable flushing after every
738 write/print operation.
739 .PP
740 If \f(CW$z\fR is associated with a buffer, this method has no effect and always
741 returns \f(CW\*(C`undef\*(C'\fR.
742 .PP
743 \&\fBNote\fR that the special variable \f(CW$|\fR \fBcannot\fR be used to set or
744 retrieve the autoflush setting.
745 .SS input_line_number
746 .IX Subsection "input_line_number"
747 .Vb 2
748 \& $z\->input_line_number()
749 \& $z\->input_line_number(EXPR)
750 .Ve
751 .PP
752 This method always returns \f(CW\*(C`undef\*(C'\fR when compressing.
753 .SS fileno
754 .IX Subsection "fileno"
755 .Vb 2
756 \& $z\->fileno()
757 \& fileno($z)
758 .Ve
759 .PP
760 If the \f(CW$z\fR object is associated with a file or a filehandle, \f(CW\*(C`fileno\*(C'\fR
761 will return the underlying file descriptor. Once the \f(CW\*(C`close\*(C'\fR method is
762 called \f(CW\*(C`fileno\*(C'\fR will return \f(CW\*(C`undef\*(C'\fR.
763 .PP
764 If the \f(CW$z\fR object is associated with a buffer, this method will return
765 \&\f(CW\*(C`undef\*(C'\fR.
766 .SS close
767 .IX Subsection "close"
768 .Vb 2
769 \& $z\->close() ;
770 \& close $z ;
771 .Ve
772 .PP
773 Flushes any pending compressed data and then closes the output file/buffer.
774 .PP
775 For most versions of Perl this method will be automatically invoked if
776 the IO::Compress::RawDeflate object is destroyed (either explicitly or by the
777 variable with the reference to the object going out of scope). The
778 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
779 these cases, the \f(CW\*(C`close\*(C'\fR method will be called automatically, but
780 not until global destruction of all live objects when the program is
781 terminating.
782 .PP
783 Therefore, if you want your scripts to be able to run on all versions
784 of Perl, you should call \f(CW\*(C`close\*(C'\fR explicitly and not rely on automatic
785 closing.
786 .PP
787 Returns true on success, otherwise 0.
788 .PP
789 If the \f(CW\*(C`AutoClose\*(C'\fR option has been enabled when the IO::Compress::RawDeflate
790 object was created, and the object is associated with a file, the
791 underlying file will also be closed.
792 .SS newStream([OPTS])
793 .IX Subsection "newStream([OPTS])"
794 Usage is
795 .PP
796 .Vb 1
797 \& $z\->newStream( [OPTS] )
798 .Ve
799 .PP
800 Closes the current compressed data stream and starts a new one.
801 .PP
802 OPTS consists of any of the options that are available when creating
803 the \f(CW$z\fR object.
804 .PP
805 See the "Constructor Options" section for more details.
806 .SS deflateParams
807 .IX Subsection "deflateParams"
808 Usage is
809 .PP
810 .Vb 1
811 \& $z\->deflateParams
812 .Ve
813 .PP
814 TODO
815 .SH Importing
816 .IX Header "Importing"
817 A number of symbolic constants are required by some methods in
818 \&\f(CW\*(C`IO::Compress::RawDeflate\*(C'\fR. None are imported by default.
819 .IP :all 5
820 .IX Item ":all"
821 Imports \f(CW\*(C`rawdeflate\*(C'\fR, \f(CW$RawDeflateError\fR and all symbolic
822 constants that can be used by \f(CW\*(C`IO::Compress::RawDeflate\*(C'\fR. Same as doing this
823 .Sp
824 .Vb 1
825 \& use IO::Compress::RawDeflate qw(rawdeflate $RawDeflateError :constants) ;
826 .Ve
827 .IP :constants 5
828 .IX Item ":constants"
829 Import all symbolic constants. Same as doing this
830 .Sp
831 .Vb 1
832 \& use IO::Compress::RawDeflate qw(:flush :level :strategy) ;
833 .Ve
834 .IP :flush 5
835 .IX Item ":flush"
836 These symbolic constants are used by the \f(CW\*(C`flush\*(C'\fR method.
837 .Sp
838 .Vb 6
839 \& Z_NO_FLUSH
840 \& Z_PARTIAL_FLUSH
841 \& Z_SYNC_FLUSH
842 \& Z_FULL_FLUSH
843 \& Z_FINISH
844 \& Z_BLOCK
845 .Ve
846 .IP :level 5
847 .IX Item ":level"
848 These symbolic constants are used by the \f(CW\*(C`Level\*(C'\fR option in the constructor.
849 .Sp
850 .Vb 4
851 \& Z_NO_COMPRESSION
852 \& Z_BEST_SPEED
853 \& Z_BEST_COMPRESSION
854 \& Z_DEFAULT_COMPRESSION
855 .Ve
856 .IP :strategy 5
857 .IX Item ":strategy"
858 These symbolic constants are used by the \f(CW\*(C`Strategy\*(C'\fR option in the constructor.
859 .Sp
860 .Vb 5
861 \& Z_FILTERED
862 \& Z_HUFFMAN_ONLY
863 \& Z_RLE
864 \& Z_FIXED
865 \& Z_DEFAULT_STRATEGY
866 .Ve
867 .SH EXAMPLES
868 .IX Header "EXAMPLES"
869 .SS "Apache::GZip Revisited"
870 .IX Subsection "Apache::GZip Revisited"
871 See IO::Compress::FAQ
872 .SS "Working with Net::FTP"
873 .IX Subsection "Working with Net::FTP"
874 See IO::Compress::FAQ
875 .SH SUPPORT
876 .IX Header "SUPPORT"
877 General feedback/questions/bug reports should be sent to
878 <https://github.com/pmqs/IO\-Compress/issues> (preferred) or
879 <https://rt.cpan.org/Public/Dist/Display.html?Name=IO\-Compress>.
880 .SH "SEE ALSO"
881 .IX Header "SEE ALSO"
882 Compress::Zlib, IO::Compress::Gzip, IO::Uncompress::Gunzip, IO::Compress::Deflate, IO::Uncompress::Inflate, IO::Uncompress::RawInflate, IO::Compress::Bzip2, IO::Uncompress::Bunzip2, IO::Compress::Lzma, IO::Uncompress::UnLzma, IO::Compress::Xz, IO::Uncompress::UnXz, IO::Compress::Lzip, IO::Uncompress::UnLzip, IO::Compress::Lzop, IO::Uncompress::UnLzop, IO::Compress::Lzf, IO::Uncompress::UnLzf, IO::Compress::Zstd, IO::Uncompress::UnZstd, IO::Uncompress::AnyInflate, IO::Uncompress::AnyUncompress
883 .PP
884 IO::Compress::FAQ
885 .PP
886 File::GlobMapper, Archive::Zip,
887 Archive::Tar,
888 IO::Zlib
889 .PP
890 For RFC 1950, 1951 and 1952 see
891 <https://datatracker.ietf.org/doc/html/rfc1950>,
892 <https://datatracker.ietf.org/doc/html/rfc1951> and
893 <https://datatracker.ietf.org/doc/html/rfc1952>
894 .PP
895 The \fIzlib\fR compression library was written by Jean-loup Gailly
896 \&\f(CW\*(C`[email protected]\*(C'\fR and Mark Adler \f(CW\*(C`[email protected]\*(C'\fR.
897 .PP
898 The primary site for the \fIzlib\fR compression library is
899 <http://www.zlib.org>.
900 .PP
901 The primary site for the \fIzlib-ng\fR compression library is
902 <https://github.com/zlib\-ng/zlib\-ng>.
903 .PP
904 The primary site for gzip is <http://www.gzip.org>.
905 .SH AUTHOR
906 .IX Header "AUTHOR"
907 This module was written by Paul Marquess, \f(CW\*(C`[email protected]\*(C'\fR.
908 .SH "MODIFICATION HISTORY"
909 .IX Header "MODIFICATION HISTORY"
910 See the Changes file.
911 .SH "COPYRIGHT AND LICENSE"
912 .IX Header "COPYRIGHT AND LICENSE"
913 Copyright (c) 2005\-2024 Paul Marquess. All rights reserved.
914 .PP
915 This program is free software; you can redistribute it and/or
916 modify it under the same terms as Perl itself.