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

OO Interface

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

Methods

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

Importing

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

EXAMPLES

AUTHOR

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

MODIFICATION HISTORY

566       See the Changes file.
567

COPYRIGHT AND LICENSE

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