IO::Compress::Xz(3pm)

1IO::Compress::Xz(3)   User Contributed Perl Documentation  IO::Compress::Xz(3)
2
3
4

NAME

6       IO::Compress::Xz - Write xz files/buffers
7

SYNOPSIS

9           use IO::Compress::Xz qw(xz $XzError) ;
10
11           my $status = xz $input => $output [,OPTS]
12               or die "xz failed: $XzError\n";
13
14           my $z = new IO::Compress::Xz $output [,OPTS]
15               or die "xz failed: $XzError\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->close() ;
33
34           $XzError ;
35
36           # IO::File mode
37
38           print $z $string;
39           printf $z $format, $string;
40           tell $z
41           eof $z
42           seek $z, $position, $whence
43           binmode $z
44           fileno $z
45           close $z ;
46

DESCRIPTION

48       WARNING -- This is a Beta release.
49
50       ·    DO NOT use in production code.
51
52       ·    The documentation is incomplete in places.
53
54       ·    Parts of the interface defined here are tentative.
55
56       ·    Please report any problems you find.
57
58       This module provides a Perl interface that allows writing xz compressed
59       data to files or buffer.
60
61       For reading xz files/buffers, see the companion module
62       IO::Uncompress::UnXz.
63

Functional Interface

65       A top-level function, "xz", is provided to carry out "one-shot"
66       compression between buffers and/or files. For finer control over the
67       compression process, see the "OO Interface" section.
68
69           use IO::Compress::Xz qw(xz $XzError) ;
70
71           xz $input => $output [,OPTS]
72               or die "xz failed: $XzError\n";
73
74       The functional interface needs Perl5.005 or better.
75
76   xz $input => $output [, OPTS]
77       "xz" expects at least two parameters, $input and $output.
78
79       The $input parameter
80
81       The parameter, $input, is used to define the source of the uncompressed
82       data.
83
84       It can take one of the following forms:
85
86       A filename
87            If the $input parameter is a simple scalar, it is assumed to be a
88            filename. This file will be opened for reading and the input data
89            will be read from it.
90
91       A filehandle
92            If the $input parameter is a filehandle, the input data will be
93            read from it.  The string '-' can be used as an alias for standard
94            input.
95
96       A scalar reference
97            If $input is a scalar reference, the input data will be read from
98            $$input.
99
100       An array reference
101            If $input is an array reference, each element in the array must be
102            a filename.
103
104            The input data will be read from each file in turn.
105
106            The complete array will be walked to ensure that it only contains
107            valid filenames before any data is compressed.
108
109       An Input FileGlob string
110            If $input is a string that is delimited by the characters "<" and
111            ">" "xz" will assume that it is an input fileglob string. The
112            input is the list of files that match the fileglob.
113
114            See File::GlobMapper for more details.
115
116       If the $input parameter is any other type, "undef" will be returned.
117
118       The $output parameter
119
120       The parameter $output is used to control the destination of the
121       compressed data. This parameter can take one of these forms.
122
123       A filename
124            If the $output parameter is a simple scalar, it is assumed to be a
125            filename.  This file will be opened for writing and the compressed
126            data will be written to it.
127
128       A filehandle
129            If the $output parameter is a filehandle, the compressed data will
130            be written to it.  The string '-' can be used as an alias for
131            standard output.
132
133       A scalar reference
134            If $output is a scalar reference, the compressed data will be
135            stored in $$output.
136
137       An Array Reference
138            If $output is an array reference, the compressed data will be
139            pushed onto the array.
140
141       An Output FileGlob
142            If $output is a string that is delimited by the characters "<" and
143            ">" "xz" will assume that it is an output fileglob string. The
144            output is the list of files that match the fileglob.
145
146            When $output is an fileglob string, $input must also be a fileglob
147            string. Anything else is an error.
148
149            See File::GlobMapper for more details.
150
151       If the $output parameter is any other type, "undef" will be returned.
152
153   Notes
154       When $input maps to multiple files/buffers and $output is a single
155       file/buffer the input files/buffers will be stored in $output as a
156       concatenated series of compressed data streams.
157
158   Optional Parameters
159       Unless specified below, the optional parameters for "xz", "OPTS", are
160       the same as those used with the OO interface defined in the
161       "Constructor Options" section below.
162
163       "AutoClose => 0|1"
164            This option applies to any input or output data streams to "xz"
165            that are filehandles.
166
167            If "AutoClose" is specified, and the value is true, it will result
168            in all input and/or output filehandles being closed once "xz" has
169            completed.
170
171            This parameter defaults to 0.
172
173       "BinModeIn => 0|1"
174            When reading from a file or filehandle, set "binmode" before
175            reading.
176
177            Defaults to 0.
178
179       "Append => 0|1"
180            The behaviour of this option is dependent on the type of output
181            data stream.
182
183            ·    A Buffer
184
185                 If "Append" is enabled, all compressed data will be append to
186                 the end of the output buffer. Otherwise the output buffer
187                 will be cleared before any compressed data is written to it.
188
189            ·    A Filename
190
191                 If "Append" is enabled, the file will be opened in append
192                 mode. Otherwise the contents of the file, if any, will be
193                 truncated before any compressed data is written to it.
194
195            ·    A Filehandle
196
197                 If "Append" is enabled, the filehandle will be positioned to
198                 the end of the file via a call to "seek" before any
199                 compressed data is written to it.  Otherwise the file pointer
200                 will not be moved.
201
202            When "Append" is specified, and set to true, it will append all
203            compressed data to the output data stream.
204
205            So when the output is a filehandle it will carry out a seek to the
206            eof before writing any compressed data. If the output is a
207            filename, it will be opened for appending. If the output is a
208            buffer, all compressed data will be appened to the existing
209            buffer.
210
211            Conversely when "Append" is not specified, or it is present and is
212            set to false, it will operate as follows.
213
214            When the output is a filename, it will truncate the contents of
215            the file before writing any compressed data. If the output is a
216            filehandle its position will not be changed. If the output is a
217            buffer, it will be wiped before any compressed data is output.
218
219            Defaults to 0.
220
221   Examples
222       To read the contents of the file "file1.txt" and write the compressed
223       data to the file "file1.txt.xz".
224
225           use strict ;
226           use warnings ;
227           use IO::Compress::Xz qw(xz $XzError) ;
228
229           my $input = "file1.txt";
230           xz $input => "$input.xz"
231               or die "xz failed: $XzError\n";
232
233       To read from an existing Perl filehandle, $input, and write the
234       compressed data to a buffer, $buffer.
235
236           use strict ;
237           use warnings ;
238           use IO::Compress::Xz qw(xz $XzError) ;
239           use IO::File ;
240
241           my $input = new IO::File "<file1.txt"
242               or die "Cannot open 'file1.txt': $!\n" ;
243           my $buffer ;
244           xz $input => \$buffer
245               or die "xz failed: $XzError\n";
246
247       To compress all files in the directory "/my/home" that match "*.txt"
248       and store the compressed data in the same directory
249
250           use strict ;
251           use warnings ;
252           use IO::Compress::Xz qw(xz $XzError) ;
253
254           xz '</my/home/*.txt>' => '<*.xz>'
255               or die "xz failed: $XzError\n";
256
257       and if you want to compress each file one at a time, this will do the
258       trick
259
260           use strict ;
261           use warnings ;
262           use IO::Compress::Xz qw(xz $XzError) ;
263
264           for my $input ( glob "/my/home/*.txt" )
265           {
266               my $output = "$input.xz" ;
267               xz $input => $output
268                   or die "Error compressing '$input': $XzError\n";
269           }
270

OO Interface

272   Constructor
273       The format of the constructor for "IO::Compress::Xz" is shown below
274
275           my $z = new IO::Compress::Xz $output [,OPTS]
276               or die "IO::Compress::Xz failed: $XzError\n";
277
278       It returns an "IO::Compress::Xz" object on success and undef on
279       failure.  The variable $XzError will contain an error message on
280       failure.
281
282       If you are running Perl 5.005 or better the object, $z, returned from
283       IO::Compress::Xz can be used exactly like an IO::File filehandle.  This
284       means that all normal output file operations can be carried out with
285       $z.  For example, to write to a compressed file/buffer you can use
286       either of these forms
287
288           $z->print("hello world\n");
289           print $z "hello world\n";
290
291       The mandatory parameter $output is used to control the destination of
292       the compressed data. This parameter can take one of these forms.
293
294       A filename
295            If the $output parameter is a simple scalar, it is assumed to be a
296            filename. This file will be opened for writing and the compressed
297            data will be written to it.
298
299       A filehandle
300            If the $output parameter is a filehandle, the compressed data will
301            be written to it.  The string '-' can be used as an alias for
302            standard output.
303
304       A scalar reference
305            If $output is a scalar reference, the compressed data will be
306            stored in $$output.
307
308       If the $output parameter is any other type, "IO::Compress::Xz"::new
309       will return undef.
310
311   Constructor Options
312       "OPTS" is any combination of the following options:
313
314       "AutoClose => 0|1"
315            This option is only valid when the $output parameter is a
316            filehandle. If specified, and the value is true, it will result in
317            the $output being closed once either the "close" method is called
318            or the "IO::Compress::Xz" object is destroyed.
319
320            This parameter defaults to 0.
321
322       "Append => 0|1"
323            Opens $output in append mode.
324
325            The behaviour of this option is dependent on the type of $output.
326
327            ·    A Buffer
328
329                 If $output is a buffer and "Append" is enabled, all
330                 compressed data will be append to the end of $output.
331                 Otherwise $output will be cleared before any data is written
332                 to it.
333
334            ·    A Filename
335
336                 If $output is a filename and "Append" is enabled, the file
337                 will be opened in append mode. Otherwise the contents of the
338                 file, if any, will be truncated before any compressed data is
339                 written to it.
340
341            ·    A Filehandle
342
343                 If $output is a filehandle, the file pointer will be
344                 positioned to the end of the file via a call to "seek" before
345                 any compressed data is written to it.  Otherwise the file
346                 pointer will not be moved.
347
348            This parameter defaults to 0.
349
350       "Preset => $preset"
351            Used to choose the compression preset.
352
353            Valid values are 0-9 and "LZMA_PRESET_DEFAULT".
354
355            0 is the fastest compression with the lowest memory usage and the
356            lowest compression.
357
358            9 is the slowest compession with the highest memory usage but with
359            the best compression.
360
361            Defaults to "LZMA_PRESET_DEFAULT".
362
363       "Extreme => 0|1"
364            Makes the compression a lot slower, but a small compression gain.
365
366            Defaults to 0.
367
368       "Check => $check"
369            Used to specify the integrrity check used in the xz data stream.
370            Valid values are "LZMA_CHECK_NONE", "LZMA_CHECK_CRC32",
371            "LZMA_CHECK_CRC64", "LZMA_CHECK_SHA256".
372
373            Defaults to "LZMA_CHECK_CRC32".
374
375       "Strict => 0|1"
376            This is a placeholder option.
377
378   Examples
379       TODO
380

Methods

382   print
383       Usage is
384
385           $z->print($data)
386           print $z $data
387
388       Compresses and outputs the contents of the $data parameter. This has
389       the same behaviour as the "print" built-in.
390
391       Returns true if successful.
392
393   printf
394       Usage is
395
396           $z->printf($format, $data)
397           printf $z $format, $data
398
399       Compresses and outputs the contents of the $data parameter.
400
401       Returns true if successful.
402
403   syswrite
404       Usage is
405
406           $z->syswrite $data
407           $z->syswrite $data, $length
408           $z->syswrite $data, $length, $offset
409
410       Compresses and outputs the contents of the $data parameter.
411
412       Returns the number of uncompressed bytes written, or "undef" if
413       unsuccessful.
414
415   write
416       Usage is
417
418           $z->write $data
419           $z->write $data, $length
420           $z->write $data, $length, $offset
421
422       Compresses and outputs the contents of the $data parameter.
423
424       Returns the number of uncompressed bytes written, or "undef" if
425       unsuccessful.
426
427   flush
428       Usage is
429
430           $z->flush;
431
432       Flushes any pending compressed data to the output file/buffer.
433
434       Returns true on success.
435
436   tell
437       Usage is
438
439           $z->tell()
440           tell $z
441
442       Returns the uncompressed file offset.
443
444   eof
445       Usage is
446
447           $z->eof();
448           eof($z);
449
450       Returns true if the "close" method has been called.
451
452   seek
453           $z->seek($position, $whence);
454           seek($z, $position, $whence);
455
456       Provides a sub-set of the "seek" functionality, with the restriction
457       that it is only legal to seek forward in the output file/buffer.  It is
458       a fatal error to attempt to seek backward.
459
460       Empty parts of the file/buffer will have NULL (0x00) bytes written to
461       them.
462
463       The $whence parameter takes one the usual values, namely SEEK_SET,
464       SEEK_CUR or SEEK_END.
465
466       Returns 1 on success, 0 on failure.
467
468   binmode
469       Usage is
470
471           $z->binmode
472           binmode $z ;
473
474       This is a noop provided for completeness.
475
476   opened
477           $z->opened()
478
479       Returns true if the object currently refers to a opened file/buffer.
480
481   autoflush
482           my $prev = $z->autoflush()
483           my $prev = $z->autoflush(EXPR)
484
485       If the $z object is associated with a file or a filehandle, this method
486       returns the current autoflush setting for the underlying filehandle. If
487       "EXPR" is present, and is non-zero, it will enable flushing after every
488       write/print operation.
489
490       If $z is associated with a buffer, this method has no effect and always
491       returns "undef".
492
493       Note that the special variable $| cannot be used to set or retrieve the
494       autoflush setting.
495
496   input_line_number
497           $z->input_line_number()
498           $z->input_line_number(EXPR)
499
500       This method always returns "undef" when compressing.
501
502   fileno
503           $z->fileno()
504           fileno($z)
505
506       If the $z object is associated with a file or a filehandle, "fileno"
507       will return the underlying file descriptor. Once the "close" method is
508       called "fileno" will return "undef".
509
510       If the $z object is is associated with a buffer, this method will
511       return "undef".
512
513   close
514           $z->close() ;
515           close $z ;
516
517       Flushes any pending compressed data and then closes the output
518       file/buffer.
519
520       For most versions of Perl this method will be automatically invoked if
521       the IO::Compress::Xz object is destroyed (either explicitly or by the
522       variable with the reference to the object going out of scope). The
523       exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In these
524       cases, the "close" method will be called automatically, but not until
525       global destruction of all live objects when the program is terminating.
526
527       Therefore, if you want your scripts to be able to run on all versions
528       of Perl, you should call "close" explicitly and not rely on automatic
529       closing.
530
531       Returns true on success, otherwise 0.
532
533       If the "AutoClose" option has been enabled when the IO::Compress::Xz
534       object was created, and the object is associated with a file, the
535       underlying file will also be closed.
536
537   newStream([OPTS])
538       Usage is
539
540           $z->newStream( [OPTS] )
541
542       Closes the current compressed data stream and starts a new one.
543
544       OPTS consists of any of the the options that are available when
545       creating the $z object.
546
547       See the "Constructor Options" section for more details.
548

Importing

550       No symbolic constants are required by this IO::Compress::Xz at present.
551
552       :all Imports "xz" and $XzError.  Same as doing this
553
554                use IO::Compress::Xz qw(xz $XzError) ;
555

EXAMPLES

557   Apache::GZip Revisited
558       See IO::Compress::Lzma::FAQ
559

AUTHOR

574       This module was written by Paul Marquess, pmqs@cpan.org.
575

MODIFICATION HISTORY

577       See the Changes file.
578

COPYRIGHT AND LICENSE

580       Copyright (c) 2005-2010 Paul Marquess. All rights reserved.
581
582       This program is free software; you can redistribute it and/or modify it
583       under the same terms as Perl itself.
584
585
586
587perl v5.12.1                      2010-07-24               IO::Compress::Xz(3)