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

OO Interface

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

Methods

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

Importing

577       No symbolic constants are required by this IO::Compress::Xz at present.
578
579       :all Imports "xz" and $XzError.  Same as doing this
580
581                use IO::Compress::Xz qw(xz $XzError) ;
582

EXAMPLES

SUPPORT

585       General feedback/questions/bug reports should be sent to
586       <https://github.com/pmqs/IO-Compress-Lzma/issues> (preferred) or
587       <https://rt.cpan.org/Public/Dist/Display.html?Name=IO-Compress-Lzma>.
588

AUTHOR

605       This module was written by Paul Marquess, "pmqs@cpan.org".
606

MODIFICATION HISTORY

608       See the Changes file.
609

COPYRIGHT AND LICENSE

611       Copyright (c) 2005-2019 Paul Marquess. All rights reserved.
612
613       This program is free software; you can redistribute it and/or modify it
614       under the same terms as Perl itself.
615
616
617
618perl v5.30.1                      2020-01-30               IO::Compress::Xz(3)