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

OO Interface

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

Methods

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

Importing

558       No symbolic constants are required by this IO::Compress::Xz at present.
559
560       :all Imports "xz" and $XzError.  Same as doing this
561
562                use IO::Compress::Xz qw(xz $XzError) ;
563

EXAMPLES

AUTHOR

579       This module was written by Paul Marquess, "pmqs@cpan.org".
580

MODIFICATION HISTORY

582       See the Changes file.
583

COPYRIGHT AND LICENSE

585       Copyright (c) 2005-2018 Paul Marquess. All rights reserved.
586
587       This program is free software; you can redistribute it and/or modify it
588       under the same terms as Perl itself.
589
590
591
592perl v5.28.0                      2018-04-04               IO::Compress::Xz(3)