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            This option is now a no-op. All files will be read in binmode.
183
184       "Append => 0|1"
185            The behaviour of this option is dependent on the type of output
186            data stream.
187
188            ·    A Buffer
189
190                 If "Append" is enabled, all compressed data will be append to
191                 the end of the output buffer. Otherwise the output buffer
192                 will be cleared before any compressed data is written to it.
193
194            ·    A Filename
195
196                 If "Append" is enabled, the file will be opened in append
197                 mode. Otherwise the contents of the file, if any, will be
198                 truncated before any compressed data is written to it.
199
200            ·    A Filehandle
201
202                 If "Append" is enabled, the filehandle will be positioned to
203                 the end of the file via a call to "seek" before any
204                 compressed data is written to it.  Otherwise the file pointer
205                 will not be moved.
206
207            When "Append" is specified, and set to true, it will append all
208            compressed data to the output data stream.
209
210            So when the output is a filehandle it will carry out a seek to the
211            eof before writing any compressed data. If the output is a
212            filename, it will be opened for appending. If the output is a
213            buffer, all compressed data will be appended to the existing
214            buffer.
215
216            Conversely when "Append" is not specified, or it is present and is
217            set to false, it will operate as follows.
218
219            When the output is a filename, it will truncate the contents of
220            the file before writing any compressed data. If the output is a
221            filehandle its position will not be changed. If the output is a
222            buffer, it will be wiped before any compressed data is output.
223
224            Defaults to 0.
225
226   Examples
227       To read the contents of the file "file1.txt" and write the compressed
228       data to the file "file1.txt.xz".
229
230           use strict ;
231           use warnings ;
232           use IO::Compress::Xz qw(xz $XzError) ;
233
234           my $input = "file1.txt";
235           xz $input => "$input.xz"
236               or die "xz failed: $XzError\n";
237
238       To read from an existing Perl filehandle, $input, and write the
239       compressed data to a buffer, $buffer.
240
241           use strict ;
242           use warnings ;
243           use IO::Compress::Xz qw(xz $XzError) ;
244           use IO::File ;
245
246           my $input = new IO::File "<file1.txt"
247               or die "Cannot open 'file1.txt': $!\n" ;
248           my $buffer ;
249           xz $input => \$buffer
250               or die "xz failed: $XzError\n";
251
252       To compress all files in the directory "/my/home" that match "*.txt"
253       and store the compressed data in the same directory
254
255           use strict ;
256           use warnings ;
257           use IO::Compress::Xz qw(xz $XzError) ;
258
259           xz '</my/home/*.txt>' => '<*.xz>'
260               or die "xz failed: $XzError\n";
261
262       and if you want to compress each file one at a time, this will do the
263       trick
264
265           use strict ;
266           use warnings ;
267           use IO::Compress::Xz qw(xz $XzError) ;
268
269           for my $input ( glob "/my/home/*.txt" )
270           {
271               my $output = "$input.xz" ;
272               xz $input => $output
273                   or die "Error compressing '$input': $XzError\n";
274           }
275

OO Interface

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

Methods

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

Importing

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

EXAMPLES

AUTHOR

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

MODIFICATION HISTORY

581       See the Changes file.
582

COPYRIGHT AND LICENSE

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