local-lib5/man/man3/IO::Compress::RawDeflate.3pm

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