IO::Compress::Lzma(3pm)

1IO::Compress::Lzma(3) User Contributed Perl DocumentationIO::Compress::Lzma(3)
2
3
4

NAME

6       IO::Compress::Lzma - Write lzma files/buffers
7

SYNOPSIS

9           use IO::Compress::Lzma qw(lzma $LzmaError) ;
10
11           my $status = lzma $input => $output [,OPTS]
12               or die "lzma failed: $LzmaError\n";
13
14           my $z = new IO::Compress::Lzma $output [,OPTS]
15               or die "lzma failed: $LzmaError\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           $LzmaError ;
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 lzma
59       compressed data to files or buffer.
60
61       For reading lzma files/buffers, see the companion module
62       IO::Uncompress::UnLzma.
63

Functional Interface

65       A top-level function, "lzma", 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::Lzma qw(lzma $LzmaError) ;
70
71           lzma $input_filename_or_reference => $output_filename_or_reference [,OPTS]
72               or die "lzma failed: $LzmaError\n";
73
74       The functional interface needs Perl5.005 or better.
75
76   lzma $input_filename_or_reference => $output_filename_or_reference [, OPTS]
77       "lzma" expects at least two parameters, $input_filename_or_reference
78       and $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 ">" "lzma" 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 ">" "lzma" 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 "lzma", "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 "lzma"
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 "lzma"
177            has 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.lzma".
229
230           use strict ;
231           use warnings ;
232           use IO::Compress::Lzma qw(lzma $LzmaError) ;
233
234           my $input = "file1.txt";
235           lzma $input => "$input.lzma"
236               or die "lzma failed: $LzmaError\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::Lzma qw(lzma $LzmaError) ;
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           lzma $input => \$buffer
250               or die "lzma failed: $LzmaError\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::Lzma qw(lzma $LzmaError) ;
258
259           lzma '</my/home/*.txt>' => '<*.lzma>'
260               or die "lzma failed: $LzmaError\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::Lzma qw(lzma $LzmaError) ;
268
269           for my $input ( glob "/my/home/*.txt" )
270           {
271               my $output = "$input.lzma" ;
272               lzma $input => $output
273                   or die "Error compressing '$input': $LzmaError\n";
274           }
275

OO Interface

277   Constructor
278       The format of the constructor for "IO::Compress::Lzma" is shown below
279
280           my $z = new IO::Compress::Lzma $output [,OPTS]
281               or die "IO::Compress::Lzma failed: $LzmaError\n";
282
283       It returns an "IO::Compress::Lzma" object on success and undef on
284       failure.  The variable $LzmaError 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::Lzma can be used exactly like an IO::File filehandle.
289       This means that all normal output file operations can be carried out
290       with $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::Lzma"::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::Lzma" 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       "Filter => $filter"
356            When present  $filter  option must be an object of type
357            "Lzma::Filter::Lzma1".  See "Lzma::Filter::Lzma" for a definition
358            of "Lzma::Filter::Lzma1".
359
360            If this option is not present an "Lzma::Filter::Lzma1" object with
361            default values will be used.
362
363       "Strict => 0|1"
364            This is a placeholder option.
365
366   Examples
367       TODO
368

Methods

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

Importing

538       No symbolic constants are required by this IO::Compress::Lzma at
539       present.
540
541       :all Imports "lzma" and $LzmaError.  Same as doing this
542
543                use IO::Compress::Lzma qw(lzma $LzmaError) ;
544

EXAMPLES

AUTHOR

562       This module was written by Paul Marquess, "pmqs@cpan.org".
563

MODIFICATION HISTORY

565       See the Changes file.
566

COPYRIGHT AND LICENSE

568       Copyright (c) 2005-2019 Paul Marquess. All rights reserved.
569
570       This program is free software; you can redistribute it and/or modify it
571       under the same terms as Perl itself.
572
573
574
575perl v5.28.1                      2019-01-05             IO::Compress::Lzma(3)