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 = IO::Compress::Xz->new( $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       This module provides a Perl interface that allows writing xz compressed
49       data to files or buffer.
50
51       For reading xz files/buffers, see the companion module
52       IO::Uncompress::UnXz.
53

Functional Interface

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

OO Interface

289   Constructor
290       The format of the constructor for "IO::Compress::Xz" is shown below
291
292           my $z = IO::Compress::Xz->new( $output [,OPTS] )
293               or die "IO::Compress::Xz failed: $XzError\n";
294
295       The constructor takes one mandatory parameter, $output, defined below
296       and zero or more "OPTS", defined in "Constructor Options".
297
298       It returns an "IO::Compress::Xz" object on success and "undef" on
299       failure.  The variable $XzError will contain an error message on
300       failure.
301
302       If you are running Perl 5.005 or better the object, $z, returned from
303       IO::Compress::Xz can be used exactly like an IO::File filehandle.  This
304       means that all normal output file operations can be carried out with
305       $z.  For example, to write to a compressed file/buffer you can use
306       either of these forms
307
308           $z->print("hello world\n");
309           print $z "hello world\n";
310
311       Below is a simple exaple of using the OO interface to create an output
312       file "myfile.xz" and write some data to it.
313
314           my $filename = "myfile.xz";
315           my $z = IO::Compress::Xz->new($filename)
316               or die "IO::Compress::Xz failed: $XzError\n";
317
318           $z->print("abcde");
319           $z->close();
320
321       See the "Examples" for more.
322
323       The mandatory parameter $output is used to control the destination of
324       the compressed data. This parameter can take one of these forms.
325
326       A filename
327            If the $output parameter is a simple scalar, it is assumed to be a
328            filename. This file will be opened for writing and the compressed
329            data will be written to it.
330
331       A filehandle
332            If the $output parameter is a filehandle, the compressed data will
333            be written to it.  The string '-' can be used as an alias for
334            standard output.
335
336       A scalar reference
337            If $output is a scalar reference, the compressed data will be
338            stored in $$output.
339
340       If the $output parameter is any other type, "IO::Compress::Xz"::new
341       will return undef.
342
343   Constructor Options
344       "OPTS" is any combination of zero or more the following options:
345
346       "AutoClose => 0|1"
347            This option is only valid when the $output parameter is a
348            filehandle. If specified, and the value is true, it will result in
349            the $output being closed once either the "close" method is called
350            or the "IO::Compress::Xz" object is destroyed.
351
352            This parameter defaults to 0.
353
354       "Append => 0|1"
355            Opens $output in append mode.
356
357            The behaviour of this option is dependent on the type of $output.
358
359            •    A Buffer
360
361                 If $output is a buffer and "Append" is enabled, all
362                 compressed data will be append to the end of $output.
363                 Otherwise $output will be cleared before any data is written
364                 to it.
365
366            •    A Filename
367
368                 If $output is a filename and "Append" is enabled, the file
369                 will be opened in append mode. Otherwise the contents of the
370                 file, if any, will be truncated before any compressed data is
371                 written to it.
372
373            •    A Filehandle
374
375                 If $output is a filehandle, the file pointer will be
376                 positioned to the end of the file via a call to "seek" before
377                 any compressed data is written to it.  Otherwise the file
378                 pointer will not be moved.
379
380            This parameter defaults to 0.
381
382       "Preset => $preset"
383            Used to choose the compression preset.
384
385            Valid values are 0-9 and "LZMA_PRESET_DEFAULT".
386
387            0 is the fastest compression with the lowest memory usage and the
388            lowest compression.
389
390            9 is the slowest compression with the highest memory usage but
391            with the best compression.
392
393            Defaults to "LZMA_PRESET_DEFAULT" (6).
394
395       "Extreme => 0|1"
396            Makes the compression a lot slower, but a small compression gain.
397
398            Defaults to 0.
399
400       "Check => $check"
401            Used to specify the integrrity check used in the xz data stream.
402            Valid values are "LZMA_CHECK_NONE", "LZMA_CHECK_CRC32",
403            "LZMA_CHECK_CRC64", "LZMA_CHECK_SHA256".
404
405            Defaults to "LZMA_CHECK_CRC32".
406
407       "Strict => 0|1"
408            This is a placeholder option.
409
410   Examples
411       Streaming
412
413       This very simple command line example demonstrates the streaming
414       capabilities of the module. The code reads data from STDIN or all the
415       files given on the commandline, compresses it, and writes the
416       compressed data to STDOUT.
417
418           use strict ;
419           use warnings ;
420           use IO::Compress::Xz qw(xz $XzError) ;
421
422           my $z = IO::Compress::Xz->new("-", Stream => 1)
423               or die "IO::Compress::Xz failed: $XzError\n";
424
425           while (<>) {
426               $z->print("abcde");
427           }
428           $z->close();
429
430       Note the use of "-" to means "STDOUT". Alternatively you can use
431       "\*STDOUT".
432
433       Compressing a file from the filesystem
434
435       To read the contents of the file "file1.txt" and write the compressed
436       data to the file "file1.txt.xz" there are a few options
437
438       Start by creating the compression object and opening the input file
439
440           use strict ;
441           use warnings ;
442           use IO::Compress::Xz qw(xz $XzError) ;
443
444           my $input = "file1.txt";
445           my $z = IO::Compress::Xz->new("file1.txt.xz")
446               or die "IO::Compress::Xz failed: $XzError\n";
447
448           # open the input file
449           open my $fh, "<", "file1.txt"
450               or die "Cannot open file1.txt: $!\n";
451
452           # loop through the input file & write to the compressed file
453           while (<$fh>) {
454               $z->print($_);
455           }
456
457           # not forgetting to close the compressed file
458           $z->close();
459

Methods

461   print
462       Usage is
463
464           $z->print($data)
465           print $z $data
466
467       Compresses and outputs the contents of the $data parameter. This has
468       the same behaviour as the "print" built-in.
469
470       Returns true if successful.
471
472   printf
473       Usage is
474
475           $z->printf($format, $data)
476           printf $z $format, $data
477
478       Compresses and outputs the contents of the $data parameter.
479
480       Returns true if successful.
481
482   syswrite
483       Usage is
484
485           $z->syswrite $data
486           $z->syswrite $data, $length
487           $z->syswrite $data, $length, $offset
488
489       Compresses and outputs the contents of the $data parameter.
490
491       Returns the number of uncompressed bytes written, or "undef" if
492       unsuccessful.
493
494   write
495       Usage is
496
497           $z->write $data
498           $z->write $data, $length
499           $z->write $data, $length, $offset
500
501       Compresses and outputs the contents of the $data parameter.
502
503       Returns the number of uncompressed bytes written, or "undef" if
504       unsuccessful.
505
506   flush
507       Usage is
508
509           $z->flush;
510
511       Flushes any pending compressed data to the output file/buffer.
512
513       Returns true on success.
514
515   tell
516       Usage is
517
518           $z->tell()
519           tell $z
520
521       Returns the uncompressed file offset.
522
523   eof
524       Usage is
525
526           $z->eof();
527           eof($z);
528
529       Returns true if the "close" method has been called.
530
531   seek
532           $z->seek($position, $whence);
533           seek($z, $position, $whence);
534
535       Provides a sub-set of the "seek" functionality, with the restriction
536       that it is only legal to seek forward in the output file/buffer.  It is
537       a fatal error to attempt to seek backward.
538
539       Empty parts of the file/buffer will have NULL (0x00) bytes written to
540       them.
541
542       The $whence parameter takes one the usual values, namely SEEK_SET,
543       SEEK_CUR or SEEK_END.
544
545       Returns 1 on success, 0 on failure.
546
547   binmode
548       Usage is
549
550           $z->binmode
551           binmode $z ;
552
553       This is a noop provided for completeness.
554
555   opened
556           $z->opened()
557
558       Returns true if the object currently refers to a opened file/buffer.
559
560   autoflush
561           my $prev = $z->autoflush()
562           my $prev = $z->autoflush(EXPR)
563
564       If the $z object is associated with a file or a filehandle, this method
565       returns the current autoflush setting for the underlying filehandle. If
566       "EXPR" is present, and is non-zero, it will enable flushing after every
567       write/print operation.
568
569       If $z is associated with a buffer, this method has no effect and always
570       returns "undef".
571
572       Note that the special variable $| cannot be used to set or retrieve the
573       autoflush setting.
574
575   input_line_number
576           $z->input_line_number()
577           $z->input_line_number(EXPR)
578
579       This method always returns "undef" when compressing.
580
581   fileno
582           $z->fileno()
583           fileno($z)
584
585       If the $z object is associated with a file or a filehandle, "fileno"
586       will return the underlying file descriptor. Once the "close" method is
587       called "fileno" will return "undef".
588
589       If the $z object is associated with a buffer, this method will return
590       "undef".
591
592   close
593           $z->close() ;
594           close $z ;
595
596       Flushes any pending compressed data and then closes the output
597       file/buffer.
598
599       For most versions of Perl this method will be automatically invoked if
600       the IO::Compress::Xz object is destroyed (either explicitly or by the
601       variable with the reference to the object going out of scope). The
602       exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In these
603       cases, the "close" method will be called automatically, but not until
604       global destruction of all live objects when the program is terminating.
605
606       Therefore, if you want your scripts to be able to run on all versions
607       of Perl, you should call "close" explicitly and not rely on automatic
608       closing.
609
610       Returns true on success, otherwise 0.
611
612       If the "AutoClose" option has been enabled when the IO::Compress::Xz
613       object was created, and the object is associated with a file, the
614       underlying file will also be closed.
615
616   newStream([OPTS])
617       Usage is
618
619           $z->newStream( [OPTS] )
620
621       Closes the current compressed data stream and starts a new one.
622
623       OPTS consists of any of the options that are available when creating
624       the $z object.
625
626       See the "Constructor Options" section for more details.
627

Importing

629       No symbolic constants are required by IO::Compress::Xz at present.
630
631       :all Imports "xz" and $XzError.  Same as doing this
632
633                use IO::Compress::Xz qw(xz $XzError) ;
634

EXAMPLES

SUPPORT

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

AUTHOR

657       This module was written by Paul Marquess, "pmqs@cpan.org".
658

MODIFICATION HISTORY

660       See the Changes file.
661

COPYRIGHT AND LICENSE

663       Copyright (c) 2005-2023 Paul Marquess. All rights reserved.
664
665       This program is free software; you can redistribute it and/or modify it
666       under the same terms as Perl itself.
667
668
669
670perl v5.38.0                      2023-07-26               IO::Compress::Xz(3)