IO::Uncompress::UnLzma(3pm)

1IO::Uncompress::UnLzma(U3s)er Contributed Perl DocumentatIiOo:n:Uncompress::UnLzma(3)
2
3
4

NAME

6       IO::Uncompress::UnLzma - Read lzma files/buffers
7

SYNOPSIS

9           use IO::Uncompress::UnLzma qw(unlzma $UnLzmaError) ;
10
11           my $status = unlzma $input => $output [,OPTS]
12               or die "unlzma failed: $UnLzmaError\n";
13
14           my $z = new IO::Uncompress::UnLzma $input [OPTS]
15               or die "unlzma failed: $UnLzmaError\n";
16
17           $status = $z->read($buffer)
18           $status = $z->read($buffer, $length)
19           $status = $z->read($buffer, $length, $offset)
20           $line = $z->getline()
21           $char = $z->getc()
22           $char = $z->ungetc()
23           $char = $z->opened()
24
25           $data = $z->trailingData()
26           $status = $z->nextStream()
27           $data = $z->getHeaderInfo()
28           $z->tell()
29           $z->seek($position, $whence)
30           $z->binmode()
31           $z->fileno()
32           $z->eof()
33           $z->close()
34
35           $UnLzmaError ;
36
37           # IO::File mode
38
39           <$z>
40           read($z, $buffer);
41           read($z, $buffer, $length);
42           read($z, $buffer, $length, $offset);
43           tell($z)
44           seek($z, $position, $whence)
45           binmode($z)
46           fileno($z)
47           eof($z)
48           close($z)
49

DESCRIPTION

51       WARNING -- This is a Beta release.
52
53       ·    DO NOT use in production code.
54
55       ·    The documentation is incomplete in places.
56
57       ·    Parts of the interface defined here are tentative.
58
59       ·    Please report any problems you find.
60
61       This module provides a Perl interface that allows the reading of lzma
62       files/buffers.
63
64       For writing lzma files/buffers, see the companion module
65       IO::Compress::Lzma.
66

Functional Interface

68       A top-level function, "unlzma", is provided to carry out "one-shot"
69       uncompression between buffers and/or files. For finer control over the
70       uncompression process, see the "OO Interface" section.
71
72           use IO::Uncompress::UnLzma qw(unlzma $UnLzmaError) ;
73
74           unlzma $input_filename_or_reference => $output_filename_or_reference [,OPTS]
75               or die "unlzma failed: $UnLzmaError\n";
76
77       The functional interface needs Perl5.005 or better.
78
79   unlzma $input_filename_or_reference => $output_filename_or_reference [,
80       OPTS]
81       "unlzma" expects at least two parameters, $input_filename_or_reference
82       and $output_filename_or_reference and zero or more optional parameters
83       (see "Optional Parameters")
84
85       The $input_filename_or_reference parameter
86
87       The parameter, $input_filename_or_reference, is used to define the
88       source of the compressed data.
89
90       It can take one of the following forms:
91
92       A filename
93            If the $input_filename_or_reference parameter is a simple scalar,
94            it is assumed to be a filename. This file will be opened for
95            reading and the input data will be read from it.
96
97       A filehandle
98            If the $input_filename_or_reference parameter is a filehandle, the
99            input data will be read from it.  The string '-' can be used as an
100            alias for standard input.
101
102       A scalar reference
103            If $input_filename_or_reference is a scalar reference, the input
104            data will be read from $$input_filename_or_reference.
105
106       An array reference
107            If $input_filename_or_reference is an array reference, each
108            element in the array must be a filename.
109
110            The input data will be read from each file in turn.
111
112            The complete array will be walked to ensure that it only contains
113            valid filenames before any data is uncompressed.
114
115       An Input FileGlob string
116            If $input_filename_or_reference is a string that is delimited by
117            the characters "<" and ">" "unlzma" will assume that it is an
118            input fileglob string. The input is the list of files that match
119            the fileglob.
120
121            See File::GlobMapper for more details.
122
123       If the $input_filename_or_reference parameter is any other type,
124       "undef" will be returned.
125
126       The $output_filename_or_reference parameter
127
128       The parameter $output_filename_or_reference is used to control the
129       destination of the uncompressed data. This parameter can take one of
130       these forms.
131
132       A filename
133            If the $output_filename_or_reference parameter is a simple scalar,
134            it is assumed to be a filename.  This file will be opened for
135            writing and the uncompressed data will be written to it.
136
137       A filehandle
138            If the $output_filename_or_reference parameter is a filehandle,
139            the uncompressed data will be written to it.  The string '-' can
140            be used as an alias for standard output.
141
142       A scalar reference
143            If $output_filename_or_reference is a scalar reference, the
144            uncompressed data will be stored in
145            $$output_filename_or_reference.
146
147       An Array Reference
148            If $output_filename_or_reference is an array reference, the
149            uncompressed data will be pushed onto the array.
150
151       An Output FileGlob
152            If $output_filename_or_reference is a string that is delimited by
153            the characters "<" and ">" "unlzma" will assume that it is an
154            output fileglob string. The output is the list of files that match
155            the fileglob.
156
157            When $output_filename_or_reference is an fileglob string,
158            $input_filename_or_reference must also be a fileglob string.
159            Anything else is an error.
160
161            See File::GlobMapper for more details.
162
163       If the $output_filename_or_reference parameter is any other type,
164       "undef" will be returned.
165
166   Notes
167       When $input_filename_or_reference maps to multiple compressed
168       files/buffers and $output_filename_or_reference is a single
169       file/buffer, after uncompression $output_filename_or_reference will
170       contain a concatenation of all the uncompressed data from each of the
171       input files/buffers.
172
173   Optional Parameters
174       The optional parameters for the one-shot function "unlzma" are (for the
175       most part) identical to those used with the OO interface defined in the
176       "Constructor Options" section. The exceptions are listed below
177
178       "AutoClose => 0|1"
179            This option applies to any input or output data streams to
180            "unlzma" that are filehandles.
181
182            If "AutoClose" is specified, and the value is true, it will result
183            in all input and/or output filehandles being closed once "unlzma"
184            has completed.
185
186            This parameter defaults to 0.
187
188       "BinModeOut => 0|1"
189            This option is now a no-op. All files will be written  in binmode.
190
191       "Append => 0|1"
192            The behaviour of this option is dependent on the type of output
193            data stream.
194
195            ·    A Buffer
196
197                 If "Append" is enabled, all uncompressed data will be append
198                 to the end of the output buffer. Otherwise the output buffer
199                 will be cleared before any uncompressed data is written to
200                 it.
201
202            ·    A Filename
203
204                 If "Append" is enabled, the file will be opened in append
205                 mode. Otherwise the contents of the file, if any, will be
206                 truncated before any uncompressed data is written to it.
207
208            ·    A Filehandle
209
210                 If "Append" is enabled, the filehandle will be positioned to
211                 the end of the file via a call to "seek" before any
212                 uncompressed data is written to it.  Otherwise the file
213                 pointer will not be moved.
214
215            When "Append" is specified, and set to true, it will append all
216            uncompressed data to the output data stream.
217
218            So when the output is a filehandle it will carry out a seek to the
219            eof before writing any uncompressed data. If the output is a
220            filename, it will be opened for appending. If the output is a
221            buffer, all uncompressed data will be appended to the existing
222            buffer.
223
224            Conversely when "Append" is not specified, or it is present and is
225            set to false, it will operate as follows.
226
227            When the output is a filename, it will truncate the contents of
228            the file before writing any uncompressed data. If the output is a
229            filehandle its position will not be changed. If the output is a
230            buffer, it will be wiped before any uncompressed data is output.
231
232            Defaults to 0.
233
234       "MultiStream => 0|1"
235            If the input file/buffer contains multiple compressed data
236            streams, this option will uncompress the whole lot as a single
237            data stream.
238
239            Defaults to 0.
240
241       "TrailingData => $scalar"
242            Returns the data, if any, that is present immediately after the
243            compressed data stream once uncompression is complete.
244
245            This option can be used when there is useful information
246            immediately following the compressed data stream, and you don't
247            know the length of the compressed data stream.
248
249            If the input is a buffer, "trailingData" will return everything
250            from the end of the compressed data stream to the end of the
251            buffer.
252
253            If the input is a filehandle, "trailingData" will return the data
254            that is left in the filehandle input buffer once the end of the
255            compressed data stream has been reached. You can then use the
256            filehandle to read the rest of the input file.
257
258            Don't bother using "trailingData" if the input is a filename.
259
260            If you know the length of the compressed data stream before you
261            start uncompressing, you can avoid having to use "trailingData" by
262            setting the "InputLength" option.
263
264   Examples
265       To read the contents of the file "file1.txt.lzma" and write the
266       uncompressed data to the file "file1.txt".
267
268           use strict ;
269           use warnings ;
270           use IO::Uncompress::UnLzma qw(unlzma $UnLzmaError) ;
271
272           my $input = "file1.txt.lzma";
273           my $output = "file1.txt";
274           unlzma $input => $output
275               or die "unlzma failed: $UnLzmaError\n";
276
277       To read from an existing Perl filehandle, $input, and write the
278       uncompressed data to a buffer, $buffer.
279
280           use strict ;
281           use warnings ;
282           use IO::Uncompress::UnLzma qw(unlzma $UnLzmaError) ;
283           use IO::File ;
284
285           my $input = new IO::File "<file1.txt.lzma"
286               or die "Cannot open 'file1.txt.lzma': $!\n" ;
287           my $buffer ;
288           unlzma $input => \$buffer
289               or die "unlzma failed: $UnLzmaError\n";
290
291       To uncompress all files in the directory "/my/home" that match
292       "*.txt.lzma" and store the compressed data in the same directory
293
294           use strict ;
295           use warnings ;
296           use IO::Uncompress::UnLzma qw(unlzma $UnLzmaError) ;
297
298           unlzma '</my/home/*.txt.lzma>' => '</my/home/#1.txt>'
299               or die "unlzma failed: $UnLzmaError\n";
300
301       and if you want to compress each file one at a time, this will do the
302       trick
303
304           use strict ;
305           use warnings ;
306           use IO::Uncompress::UnLzma qw(unlzma $UnLzmaError) ;
307
308           for my $input ( glob "/my/home/*.txt.lzma" )
309           {
310               my $output = $input;
311               $output =~ s/.lzma// ;
312               unlzma $input => $output
313                   or die "Error compressing '$input': $UnLzmaError\n";
314           }
315

OO Interface

317   Constructor
318       The format of the constructor for IO::Uncompress::UnLzma is shown below
319
320           my $z = new IO::Uncompress::UnLzma $input [OPTS]
321               or die "IO::Uncompress::UnLzma failed: $UnLzmaError\n";
322
323       Returns an "IO::Uncompress::UnLzma" object on success and undef on
324       failure.  The variable $UnLzmaError will contain an error message on
325       failure.
326
327       If you are running Perl 5.005 or better the object, $z, returned from
328       IO::Uncompress::UnLzma can be used exactly like an IO::File filehandle.
329       This means that all normal input file operations can be carried out
330       with $z.  For example, to read a line from a compressed file/buffer you
331       can use either of these forms
332
333           $line = $z->getline();
334           $line = <$z>;
335
336       The mandatory parameter $input is used to determine the source of the
337       compressed data. This parameter can take one of three forms.
338
339       A filename
340            If the $input parameter is a scalar, it is assumed to be a
341            filename. This file will be opened for reading and the compressed
342            data will be read from it.
343
344       A filehandle
345            If the $input parameter is a filehandle, the compressed data will
346            be read from it.  The string '-' can be used as an alias for
347            standard input.
348
349       A scalar reference
350            If $input is a scalar reference, the compressed data will be read
351            from $$input.
352
353   Constructor Options
354       The option names defined below are case insensitive and can be
355       optionally prefixed by a '-'.  So all of the following are valid
356
357           -AutoClose
358           -autoclose
359           AUTOCLOSE
360           autoclose
361
362       OPTS is a combination of the following options:
363
364       "AutoClose => 0|1"
365            This option is only valid when the $input parameter is a
366            filehandle. If specified, and the value is true, it will result in
367            the file being closed once either the "close" method is called or
368            the IO::Uncompress::UnLzma object is destroyed.
369
370            This parameter defaults to 0.
371
372       "MultiStream => 0|1"
373            Allows multiple concatenated compressed streams to be treated as a
374            single compressed stream. Decompression will stop once either the
375            end of the file/buffer is reached, an error is encountered
376            (premature eof, corrupt compressed data) or the end of a stream is
377            not immediately followed by the start of another stream.
378
379            This parameter defaults to 0.
380
381       "Prime => $string"
382            This option will uncompress the contents of $string before
383            processing the input file/buffer.
384
385            This option can be useful when the compressed data is embedded in
386            another file/data structure and it is not possible to work out
387            where the compressed data begins without having to read the first
388            few bytes. If this is the case, the uncompression can be primed
389            with these bytes using this option.
390
391       "Transparent => 0|1"
392            If this option is set and the input file/buffer is not compressed
393            data, the module will allow reading of it anyway.
394
395            In addition, if the input file/buffer does contain compressed data
396            and there is non-compressed data immediately following it, setting
397            this option will make this module treat the whole file/buffer as a
398            single data stream.
399
400            This option defaults to 1.
401
402       "BlockSize => $num"
403            When reading the compressed input data, IO::Uncompress::UnLzma
404            will read it in blocks of $num bytes.
405
406            This option defaults to 4096.
407
408       "InputLength => $size"
409            When present this option will limit the number of compressed bytes
410            read from the input file/buffer to $size. This option can be used
411            in the situation where there is useful data directly after the
412            compressed data stream and you know beforehand the exact length of
413            the compressed data stream.
414
415            This option is mostly used when reading from a filehandle, in
416            which case the file pointer will be left pointing to the first
417            byte directly after the compressed data stream.
418
419            This option defaults to off.
420
421       "Append => 0|1"
422            This option controls what the "read" method does with uncompressed
423            data.
424
425            If set to 1, all uncompressed data will be appended to the output
426            parameter of the "read" method.
427
428            If set to 0, the contents of the output parameter of the "read"
429            method will be overwritten by the uncompressed data.
430
431            Defaults to 0.
432
433       "Strict => 0|1"
434            This option controls whether the extra checks defined below are
435            used when carrying out the decompression. When Strict is on, the
436            extra tests are carried out, when Strict is off they are not.
437
438            The default for this option is off.
439
440   Examples
441       TODO
442

Methods

444   read
445       Usage is
446
447           $status = $z->read($buffer)
448
449       Reads a block of compressed data (the size of the compressed block is
450       determined by the "Buffer" option in the constructor), uncompresses it
451       and writes any uncompressed data into $buffer. If the "Append"
452       parameter is set in the constructor, the uncompressed data will be
453       appended to the $buffer parameter. Otherwise $buffer will be
454       overwritten.
455
456       Returns the number of uncompressed bytes written to $buffer, zero if
457       eof or a negative number on error.
458
459   read
460       Usage is
461
462           $status = $z->read($buffer, $length)
463           $status = $z->read($buffer, $length, $offset)
464
465           $status = read($z, $buffer, $length)
466           $status = read($z, $buffer, $length, $offset)
467
468       Attempt to read $length bytes of uncompressed data into $buffer.
469
470       The main difference between this form of the "read" method and the
471       previous one, is that this one will attempt to return exactly $length
472       bytes. The only circumstances that this function will not is if end-of-
473       file or an IO error is encountered.
474
475       Returns the number of uncompressed bytes written to $buffer, zero if
476       eof or a negative number on error.
477
478   getline
479       Usage is
480
481           $line = $z->getline()
482           $line = <$z>
483
484       Reads a single line.
485
486       This method fully supports the use of the variable $/ (or
487       $INPUT_RECORD_SEPARATOR or $RS when "English" is in use) to determine
488       what constitutes an end of line. Paragraph mode, record mode and file
489       slurp mode are all supported.
490
491   getc
492       Usage is
493
494           $char = $z->getc()
495
496       Read a single character.
497
498   ungetc
499       Usage is
500
501           $char = $z->ungetc($string)
502
503   getHeaderInfo
504       Usage is
505
506           $hdr  = $z->getHeaderInfo();
507           @hdrs = $z->getHeaderInfo();
508
509       This method returns either a hash reference (in scalar context) or a
510       list or hash references (in array context) that contains information
511       about each of the header fields in the compressed data stream(s).
512
513   tell
514       Usage is
515
516           $z->tell()
517           tell $z
518
519       Returns the uncompressed file offset.
520
521   eof
522       Usage is
523
524           $z->eof();
525           eof($z);
526
527       Returns true if the end of the compressed input stream has been
528       reached.
529
530   seek
531           $z->seek($position, $whence);
532           seek($z, $position, $whence);
533
534       Provides a sub-set of the "seek" functionality, with the restriction
535       that it is only legal to seek forward in the input file/buffer.  It is
536       a fatal error to attempt to seek backward.
537
538       Note that the implementation of "seek" in this module does not provide
539       true random access to a compressed file/buffer. It  works by
540       uncompressing data from the current offset in the file/buffer until it
541       reaches the uncompressed offset specified in the parameters to "seek".
542       For very small files this may be acceptable behaviour. For large files
543       it may cause an unacceptable delay.
544
545       The $whence parameter takes one the usual values, namely SEEK_SET,
546       SEEK_CUR or SEEK_END.
547
548       Returns 1 on success, 0 on failure.
549
550   binmode
551       Usage is
552
553           $z->binmode
554           binmode $z ;
555
556       This is a noop provided for completeness.
557
558   opened
559           $z->opened()
560
561       Returns true if the object currently refers to a opened file/buffer.
562
563   autoflush
564           my $prev = $z->autoflush()
565           my $prev = $z->autoflush(EXPR)
566
567       If the $z object is associated with a file or a filehandle, this method
568       returns the current autoflush setting for the underlying filehandle. If
569       "EXPR" is present, and is non-zero, it will enable flushing after every
570       write/print operation.
571
572       If $z is associated with a buffer, this method has no effect and always
573       returns "undef".
574
575       Note that the special variable $| cannot be used to set or retrieve the
576       autoflush setting.
577
578   input_line_number
579           $z->input_line_number()
580           $z->input_line_number(EXPR)
581
582       Returns the current uncompressed line number. If "EXPR" is present it
583       has the effect of setting the line number. Note that setting the line
584       number does not change the current position within the file/buffer
585       being read.
586
587       The contents of $/ are used to determine what constitutes a line
588       terminator.
589
590   fileno
591           $z->fileno()
592           fileno($z)
593
594       If the $z object is associated with a file or a filehandle, "fileno"
595       will return the underlying file descriptor. Once the "close" method is
596       called "fileno" will return "undef".
597
598       If the $z object is associated with a buffer, this method will return
599       "undef".
600
601   close
602           $z->close() ;
603           close $z ;
604
605       Closes the output file/buffer.
606
607       For most versions of Perl this method will be automatically invoked if
608       the IO::Uncompress::UnLzma object is destroyed (either explicitly or by
609       the variable with the reference to the object going out of scope). The
610       exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In these
611       cases, the "close" method will be called automatically, but not until
612       global destruction of all live objects when the program is terminating.
613
614       Therefore, if you want your scripts to be able to run on all versions
615       of Perl, you should call "close" explicitly and not rely on automatic
616       closing.
617
618       Returns true on success, otherwise 0.
619
620       If the "AutoClose" option has been enabled when the
621       IO::Uncompress::UnLzma object was created, and the object is associated
622       with a file, the underlying file will also be closed.
623
624   nextStream
625       Usage is
626
627           my $status = $z->nextStream();
628
629       Skips to the next compressed data stream in the input file/buffer. If a
630       new compressed data stream is found, the eof marker will be cleared and
631       $.  will be reset to 0.
632
633       Returns 1 if a new stream was found, 0 if none was found, and -1 if an
634       error was encountered.
635
636   trailingData
637       Usage is
638
639           my $data = $z->trailingData();
640
641       Returns the data, if any, that is present immediately after the
642       compressed data stream once uncompression is complete. It only makes
643       sense to call this method once the end of the compressed data stream
644       has been encountered.
645
646       This option can be used when there is useful information immediately
647       following the compressed data stream, and you don't know the length of
648       the compressed data stream.
649
650       If the input is a buffer, "trailingData" will return everything from
651       the end of the compressed data stream to the end of the buffer.
652
653       If the input is a filehandle, "trailingData" will return the data that
654       is left in the filehandle input buffer once the end of the compressed
655       data stream has been reached. You can then use the filehandle to read
656       the rest of the input file.
657
658       Don't bother using "trailingData" if the input is a filename.
659
660       If you know the length of the compressed data stream before you start
661       uncompressing, you can avoid having to use "trailingData" by setting
662       the "InputLength" option in the constructor.
663

Importing

665       No symbolic constants are required by this IO::Uncompress::UnLzma at
666       present.
667
668       :all Imports "unlzma" and $UnLzmaError.  Same as doing this
669
670                use IO::Uncompress::UnLzma qw(unlzma $UnLzmaError) ;
671

EXAMPLES

SUPPORT

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

AUTHOR

694       This module was written by Paul Marquess, "pmqs@cpan.org".
695

MODIFICATION HISTORY

697       See the Changes file.
698

COPYRIGHT AND LICENSE

700       Copyright (c) 2005-2019 Paul Marquess. All rights reserved.
701
702       This program is free software; you can redistribute it and/or modify it
703       under the same terms as Perl itself.
704
705
706
707perl v5.30.1                      2020-01-30         IO::Uncompress::UnLzma(3)