Compress::Raw::Lzma(3pm)

1Compress::Raw::Lzma(3)User Contributed Perl DocumentationCompress::Raw::Lzma(3)
2
3
4

NAME

6       Compress::Raw::Lzma - Low-Level Interface to lzma compression library
7

SYNOPSIS

9           use Compress::Raw::Lzma ;
10
11           # Encoders
12           my ($lz, $status) = new Compress::Raw::Lzma::EasyEncoder [OPTS]
13               or die "Cannot create lzma object: $status\n";
14
15           my ($lz, $status) = new Compress::Raw::Lzma::AloneEncoder [OPTS]
16               or die "Cannot create lzma object: $status\n";
17
18           my ($lz, $status) = new Compress::Raw::Lzma::StreamEncoder [OPTS]
19               or die "Cannot create lzma object: $status\n";
20
21           my ($lz, $status) = new Compress::Raw::Lzma::RawEncoder [OPTS]
22               or die "Cannot create lzma object: $status\n";
23
24           $status = $lz->code($input, $output);
25           $status = $lz->flush($output);
26
27           # Decoders
28           my ($lz, $status) = new Compress::Raw::Lzma::AloneDecoder [OPTS]
29               or die "Cannot create bunzip2 object: $status\n";
30
31           my ($lz, $status) = new Compress::Raw::Lzma::AutoDecoder [OPTS]
32               or die "Cannot create bunzip2 object: $status\n";
33
34           my ($lz, $status) = new Compress::Raw::Lzma::StreamDecoder [OPTS]
35               or die "Cannot create bunzip2 object: $status\n";
36
37           my ($lz, $status) = new Compress::Raw::Lzma::RawDecoder [OPTS]
38               or die "Cannot create bunzip2 object: $status\n";
39
40           $status = $lz->code($input, $output);
41
42           my $version = Compress::Raw::Lzma::lzma_version_number();
43           my $version = Compress::Raw::Lzma::lzma_version_string();
44

DESCRIPTION

46       "Compress::Raw::Lzma" provides an interface to the in-memory
47       compression/uncompression functions from the lzma compression library.
48
49       Although the primary purpose for the existence of "Compress::Raw::Lzma"
50       is for use by the  "IO::Compress::Lzma", "IO::Uncompress::UnLzma",
51       "IO::Compress::Xz" and "IO::Uncompress::UnXz" modules, it can be used
52       on its own for simple compression/uncompression tasks.
53
54       There are two functions, called "code" and "flush", used in all the
55       compression and uncompression interfaces defined in this module. By
56       default both of these functions overwrites any data stored in its
57       output buffer parameter. If you want to compress/uncompress to a single
58       buffer, and have "code" and "flush" append to that buffer, enable the
59       "AppendOutput" option when you create the compression/decompression
60       object.
61

Compression

63       There are four compression interfaces available in this module.
64
65       Compress::Raw::Lzma::EasyEncoder =item
66       Compress::Raw::Lzma::AloneEncoder =item
67       Compress::Raw::Lzma::StreamEncoder =item
68       Compress::Raw::Lzma::RawEncoder
69
70   ($z, $status) = new Compress::Raw::Lzma::EasyEncoder [OPTS];
71       Creates a new xz compression object.
72
73       If successful, it will return the initialised compression object, $z
74       and a $status of "LZMA_OK" in a list context. In scalar context it
75       returns the deflation object, $z, only.
76
77       If not successful, the returned compression object, $z, will be undef
78       and $status will hold the an lzma error code.
79
80       Below is a list of the valid options:
81
82       Preset => $preset
83            Used to choose the compression preset.
84
85            Valid values are 0-9 and "LZMA_PRESET_DEFAULT".
86
87            0 is the fastest compression with the lowest memory usage and the
88            lowest compression.
89
90            9 is the slowest compression with the highest memory usage but
91            with the best compression.
92
93            Defaults to "LZMA_PRESET_DEFAULT".
94
95       Extreme => 0|1
96            Makes the compression a lot slower, but a small compression gain.
97
98            Defaults to 0.
99
100       Check => $check
101            Used to specify the integrity check used in the xz data stream.
102            Valid values are "LZMA_CHECK_NONE", "LZMA_CHECK_CRC32",
103            "LZMA_CHECK_CRC64", "LZMA_CHECK_SHA256".
104
105            Defaults to "LZMA_CHECK_CRC32".
106
107       AppendOutput => 0|1
108            Controls whether the compressed data is appended to the output
109            buffer in the "code" and "flush" methods.
110
111            Defaults to 0.  (Note in versions of this module prior to 2.072
112            the default value was incorrectly documented as 1).
113
114       BufSize => $number
115            Sets the initial size for the output buffer used by the "$d->code"
116            method. If the buffer has to be reallocated to increase the size,
117            it will grow in increments of "Bufsize".
118
119            Defaults to 16k.
120
121   ($z, $status) = new Compress::Raw::Lzma::AloneEncoder [OPTS];
122       Creates a legacy lzma compression object. This format is also know as
123       lzma_alone.
124
125       If successful, it will return the initialised compression object, $z
126       and a $status of "LZMA_OK" in a list context. In scalar context it
127       returns the deflation object, $z, only.
128
129       If not successful, the returned compression object, $z, will be undef
130       and $status will hold the an lzma error code.
131
132       Below is a list of the valid options:
133
134       Filter => $filter
135            The  $filter  option must be an object of type
136            "Lzma::Filter::Lzma1".  See "Lzma::Filter::Lzma" in
137            Compress::Raw::Lzma for a definition of "Lzma::Filter::Lzma1".
138
139            If this option is not present an "Lzma::Filter::Lzma1" object with
140            default values will be used.
141
142       AppendOutput => 0|1
143            Controls whether the compressed data is appended to the output
144            buffer in the "code" and "flush" methods.
145
146            Defaults to 0.  (Note in versions of this module prior to 2.072
147            the default value was incorrectly documented as 1).
148
149       BufSize => $number
150            Sets the initial size for the output buffer used by the "$d->code"
151            method. If the buffer has to be reallocated to increase the size,
152            it will grow in increments of "Bufsize".
153
154            Defaults to 16k.
155
156   ($z, $status) = new Compress::Raw::Lzma::StreamEncoder [OPTS];
157       Creates a xz compression object.
158
159       If successful, it will return the initialised compression object, $z
160       and a $status of "LZMA_OK" in a list context. In scalar context it
161       returns the deflation object, $z, only.
162
163       If not successful, the returned compression object, $z, will be undef
164       and $status will hold the an lzma error code.
165
166       Below is a list of the valid options:
167
168       Filter => $filter =item Filter => [$filter1, $filter2,...]
169            This option is used to change the bahaviour of the StreamEncoder
170            by applying between one and "LZMA_FILTERS_MAX" filters to the data
171            stream during compression. See "Filters" for more details on the
172            available filters.
173
174            If this option is present it must either contain a single
175            "Lzma::Filter::Lzma" filter object or an array reference
176            containing between one and "LZMA_FILTERS_MAX" filter objects.
177
178            If this option is not present an "Lzma::Filter::Lzma2" object with
179            default values will be used.
180
181       Check => $check
182            Used to specify the integrity check used in the xz data stream.
183            Valid values are "LZMA_CHECK_NONE", "LZMA_CHECK_CRC32",
184            "LZMA_CHECK_CRC64", "LZMA_CHECK_SHA256".
185
186            Defaults to "LZMA_CHECK_CRC32".
187
188       AppendOutput => 0|1
189            Controls whether the compressed data is appended to the output
190            buffer in the "code" and "flush" methods.
191
192            Defaults to 0.  (Note in versions of this module prior to 2.072
193            the default value was incorrectly documented as 1).
194
195       BufSize => $number
196            Sets the initial size for the output buffer used by the "$d->code"
197            method. If the buffer has to be reallocated to increase the size,
198            it will grow in increments of "Bufsize".
199
200            Defaults to 16k.
201
202   ($z, $status) = new Compress::Raw::Lzma::RawEncoder [OPTS];
203       Low level access to lzma.
204
205       If successful, it will return the initialised compression object, $z
206       and a $status of "LZMA_OK" in a list context. In scalar context it
207       returns the deflation object, $z, only.
208
209       If not successful, the returned compression object, $z, will be undef
210       and $status will hold the an lzma error code.
211
212       Below is a list of the valid options:
213
214       Filter => $filter =item Filter => [$filter1, $filter2,...]
215            This option is used to change the bahaviour of the RawEncoder by
216            applying between one and "LZMA_FILTERS_MAX" filters to the data
217            stream during compression. See "Filters" for more details on the
218            available filters.
219
220            If this option is present it must either contain a single
221            "Lzma::Filter::Lzma" filter object or an array reference
222            containing between one and "LZMA_FILTERS_MAX" filter objects.
223
224            If this option is not present an "Lzma::Filter::Lzma2" object with
225            default values will be used.
226
227       AppendOutput => 0|1
228            Controls whether the compressed data is appended to the output
229            buffer in the "code" and "flush" methods.
230
231            Defaults to 0.  (Note in versions of this module prior to 2.072
232            the default value was incorrectly documented as 1).
233
234       BufSize => $number
235            Sets the initial size for the output buffer used by the "$d->code"
236            method. If the buffer has to be reallocated to increase the size,
237            it will grow in increments of "Bufsize".
238
239            Defaults to 16k.
240
241       ForZip => 1/0
242            This boolean option is used to enable prefixing the compressed
243            data stream with an encoded copy of the filter properties.
244
245            Defaults to 0.
246
247   $status = $lz->code($input, $output);
248       Reads the contents of $input, compresses it and writes the compressed
249       data to $output.
250
251       Returns "LZMA_OK" on success and an "lzma" error code on failure.
252
253       If "appendOutput" is enabled in the constructor for the lzma object,
254       the compressed data will be appended to $output. If not enabled,
255       $output will be truncated before the compressed data is written to it.
256
257   $status = $lz->flush($output, LZMA_FINISH);
258       Flushes any pending compressed data to $output. By default it
259       terminates the compressed data stream.
260
261       Returns "LZMA_OK" on success and an "lzma" error code on failure.
262
263   Example
264       TODO
265

Uncompression

267       There are four uncompression interfaces available in this module.
268
269       Compress::Raw::Lzma::AutoDecoder =item
270       Compress::Raw::Lzma::AloneDecoder =item
271       Compress::Raw::Lzma::StreamDecoder =item
272       Compress::Raw::Lzma::RawDecoder
273
274   ($z, $status) = new Compress::Raw::Lzma::AutoDecoder [OPTS] ;
275       Create an object that can uncompress any of the compressed data streams
276       that can be created by this module.
277
278       If successful, it will return the initialised uncompression object, $z
279       and a $status of "LZMA_OK" in a list context. In scalar context it
280       returns the deflation object, $z, only.
281
282       If not successful, the returned uncompression object, $z, will be undef
283       and $status will hold the an lzma error code.
284
285       Below is a list of the valid options:
286
287       -MemLimit
288            The number of bytes to use when uncompressing.
289
290            Default is unlimited.
291
292       -Bufsize
293            Sets the initial size for the output buffer used by the "$i->code"
294            method. If the output buffer in this method has to be reallocated
295            to increase the size, it will grow in increments of "Bufsize".
296
297            Default is 16k.
298
299       -AppendOutput
300            This option controls how data is written to the output buffer by
301            the "$i->code" method.
302
303            If the option is set to false, the output buffer in the "$i->code"
304            method will be truncated before uncompressed data is written to
305            it.
306
307            If the option is set to true, uncompressed data will be appended
308            to the output buffer by the "$i->code" method.
309
310            This option defaults to false.
311
312       -ConsumeInput
313            If set to true, this option will remove compressed data from the
314            input buffer of the "$i->code" method as the uncompression
315            progresses.
316
317            This option can be useful when you are processing compressed data
318            that is embedded in another file/buffer. In this case the data
319            that immediately follows the compressed stream will be left in the
320            input buffer.
321
322            This option defaults to true.
323
324       -LimitOutput
325            The "LimitOutput" option changes the behavior of the "$i->code"
326            method so that the amount of memory used by the output buffer can
327            be limited.
328
329            When "LimitOutput" is used the size of the output buffer used will
330            either be the value of the "Bufsize" option or the amount of
331            memory already allocated to $output, whichever is larger.
332            Predicting the output size available is tricky, so don't rely on
333            getting an exact output buffer size.
334
335            When "LimitOutout" is not specified "$i->code" will use as much
336            memory as it takes to write all the uncompressed data it creates
337            by uncompressing the input buffer.
338
339            If "LimitOutput" is enabled, the "ConsumeInput" option will also
340            be enabled.
341
342            This option defaults to false.
343
344            See "The LimitOutput option" for a discussion on why "LimitOutput"
345            is needed and how to use it.
346
347   ($z, $status) = new Compress::Raw::Lzma::AloneDecoder [OPTS] ;
348       Create an object that can uncompress an lzma_alone data stream.
349
350       If successful, it will return the initialised uncompression object, $z
351       and a $status of "LZMA_OK" in a list context. In scalar context it
352       returns the deflation object, $z, only.
353
354       If not successful, the returned uncompression object, $z, will be undef
355       and $status will hold the an lzma error code.
356
357       Below is a list of the valid options:
358
359       -MemLimit
360            The number of bytes to use when uncompressing.
361
362            Default is unlimited.
363
364       -Bufsize
365            Sets the initial size for the output buffer used by the "$i->code"
366            method. If the output buffer in this method has to be reallocated
367            to increase the size, it will grow in increments of "Bufsize".
368
369            Default is 16k.
370
371       -AppendOutput
372            This option controls how data is written to the output buffer by
373            the "$i->code" method.
374
375            If the option is set to false, the output buffer in the "$i->code"
376            method will be truncated before uncompressed data is written to
377            it.
378
379            If the option is set to true, uncompressed data will be appended
380            to the output buffer by the "$i->code" method.
381
382            This option defaults to false.
383
384       -ConsumeInput
385            If set to true, this option will remove compressed data from the
386            input buffer of the "$i->code" method as the uncompression
387            progresses.
388
389            This option can be useful when you are processing compressed data
390            that is embedded in another file/buffer. In this case the data
391            that immediately follows the compressed stream will be left in the
392            input buffer.
393
394            This option defaults to true.
395
396       -LimitOutput
397            The "LimitOutput" option changes the behavior of the "$i->code"
398            method so that the amount of memory used by the output buffer can
399            be limited.
400
401            When "LimitOutput" is used the size of the output buffer used will
402            either be the value of the "Bufsize" option or the amount of
403            memory already allocated to $output, whichever is larger.
404            Predicting the output size available is tricky, so don't rely on
405            getting an exact output buffer size.
406
407            When "LimitOutout" is not specified "$i->code" will use as much
408            memory as it takes to write all the uncompressed data it creates
409            by uncompressing the input buffer.
410
411            If "LimitOutput" is enabled, the "ConsumeInput" option will also
412            be enabled.
413
414            This option defaults to false.
415
416            See "The LimitOutput option" for a discussion on why "LimitOutput"
417            is needed and how to use it.
418
419   $status = $z->code($input, $output);
420       Uncompresses $input and writes the uncompressed data to $output.
421
422       Returns "LZMA_OK" if the uncompression was successful, but the end of
423       the compressed data stream has not been reached. Returns
424       "LZMA_STREAM_END" on successful uncompression and the end of the
425       compression stream has been reached.
426
427       If "consumeInput" is enabled in the constructor for the lzma object,
428       $input will have all compressed data removed from it after
429       uncompression. On "LZMA_OK" return this will mean that $input will be
430       an empty string; when "LZMA_STREAM_END" $input will either be an empty
431       string or will contain whatever data immediately followed the
432       compressed data stream.
433
434       If "appendOutput" is enabled in the constructor for the lzma object,
435       the uncompressed data will be appended to $output. If not enabled,
436       $output will be truncated before the uncompressed data is written to
437       it.
438

Filters

440       TODO - more here
441
442       A number of the Lzma compression interfaces (namely
443       "Compress::Raw::Lzma::StreamEncoder" &
444       "Compress::Raw::Lzma::AloneEncoder") and the raw lzma uncompression
445       interface make use of filters. These filters are used to change the
446       behaviour of compression (and raw uncompression).
447
448       All Lzma Filters are sub-classed from the "Lzma::Filter" base-class.
449
450   Lzma::Filter::Lzma
451       The "Lzma::Filter::Lzma" class is used to... TODO - more here
452
453       There are two subclasses of "Lzma::Filter::Lzma", namely
454       "Lzma::Filter::Lzma1" and "Lzma::Filter::Lzma2".
455
456       The former is typically used with "Compress::Raw::Lzma::AloneEncoder".
457       The latter with "Compress::Raw::Lzma::StreamEncoder".
458
459       When using Lzma filters an "Lzma::Filter::Lzma" must be included and it
460       must be the last filter in the chain. There can only be one
461       "Lzma::Filter::Lzma" filter in any filter chain.
462
463       The "Lzma::Filter::Lzma" construction takes the following options.
464
465       DictSize => $value
466            Dictionary size in bytes. This controls how many bytes of the
467            recently processed uncompressed data is kept in memory. The size
468            of the dictionary must be at least "LZMA_DICT_SIZE_MIN".
469
470            Defaults to "LZMA_DICT_SIZE_DEFAULT".
471
472       Lc => $value
473            Number of literal context bits.
474
475            How many of the highest bits of the previous uncompressed eight-
476            bit byte (also known as `literal') are taken into account when
477            predicting the bits of the next literal.
478
479            $value must be a number between "LZMA_LCLP_MIN" and
480            "LZMA_LCLP_MAX".
481
482            Note the sum of the "Lc" and "Lp" options cannot exceed 4.
483
484            Defaults to "LZMA_LC_DEFAULT".
485
486       Lp => $value
487            Number of literal position bits.
488
489            How many of the lowest bits of the current position (number of
490            bytes from the beginning of the uncompressed data) in the
491            uncompressed data is taken into account when predicting the bits
492            of the next literal (a single eight-bit byte).
493
494            Defaults to "LZMA_LP_DEFAULT".
495
496       Pb => $value
497            Number of position bits
498
499            How many of the lowest bits of the current position in the
500            uncompressed data is taken into account when estimating
501            probabilities of matches. A match is a sequence of bytes for which
502            a matching sequence is found from the dictionary and thus can be
503            stored as distance-length pair.
504
505            $value must be a number between "LZMA_PB_MIN" and "LZMA_PB_MAX".
506
507            Defaults to "LZMA_PB_DEFAULT".
508
509       Mode => $value
510            The Compression Mode. Valid values are "LZMA_MODE_FAST" and
511            "LZMA_MODE_NORMAL".
512
513            Defaults to "LZMA_MODE_NORMAL".
514
515       Nice => $value
516            Nice length of a match
517
518            Defaults to 64.
519
520       Mf => $value
521            Defines which Match Finder to use. Valid values are "LZMA_MF_HC3"
522            "LZMA_MF_HC4", "LZMA_MF_BT2" "LZMA_MF_BT3" and "LZMA_MF_BT4".
523
524            Defaults to "LZMA_MF_BT4".
525
526       Depth => $value
527            Maximum search depth in the match finder.
528
529            Defaults to 0.
530
531   Lzma::Filter::BCJ
532       The sub-classes of "Lzma::Filter::BCJ" are the Branch/Call/Jump
533       conversion filters. These filters are used to rewrite executable binary
534       code for a number of processor architectures.  None of these classes
535       take any options.
536
537       Lzma::Filter::X86
538            Filter for x86 binaries.
539
540       Lzma::Filter::PowerPC
541            Filter for Big endian PowerPC binaries.
542
543       Lzma::Filter::IA64
544            Filter for IA64 (Itanium) binaries.
545
546       Lzma::Filter::ARM
547            Filter for ARM binaries.
548
549       Lzma::Filter::ARMThumb
550            Filter for ARMThumb binaries.
551
552       Lzma::Filter::Sparc
553            Filter for Sparc binaries.
554
555   Lzma::Filter::Delta
556       Usage is
557
558           Lzma::Filter::Delta [OPTS]
559
560       Type => $type
561            Defines the type of Delta calculation. The only available type
562            (and therefore the default) is "LZMA_DELTA_TYPE_BYTE",
563
564       Distance => $value
565            Defines the Delta Distance. $value must be a number between
566            "LZMA_DELTA_DIST_MIN" and "LZMA_DELTA_DIST_MAX".
567
568            Default is "LZMA_DELTA_DIST_MIN".
569

Misc

571   my $version = Compress::Raw::Lzma::lzma_version_number();
572       Returns the version of the underlying lzma library this module is using
573       at run-time as a number.
574
575   my $version = Compress::Raw::Lzma::lzma_version_string();
576       Returns the version of the underlying lzma library this module is using
577       at run-time as a string.
578
579   my $version = Compress::Raw::Lzma::LZMA_VERSION();
580       Returns the version of the underlying lzma library this module was
581       using at compile-time as a number.
582
583   my $version = Compress::Raw::Lzma::LZMA_VERSION_STRING();
584       Returns the version of the underlying lzma library this module was
585       using at compile-time as a string.
586

Constants

588       The following lzma constants are exported by this module
589
590       TODO - more here
591

SUPPORT

593       General feedback/questions/bug reports should be sent to
594       <https://github.com/pmqs/Compress-Raw-Lzma/issues> (preferred) or
595       <https://rt.cpan.org/Public/Dist/Display.html?Name=Compress-Raw-Lzma>.
596

AUTHOR

613       This module was written by Paul Marquess, "pmqs@cpan.org".
614

MODIFICATION HISTORY

616       See the Changes file.
617

COPYRIGHT AND LICENSE

619       Copyright (c) 2005-2020 Paul Marquess. All rights reserved.
620
621       This program is free software; you can redistribute it and/or modify it
622       under the same terms as Perl itself.
623
624
625
626perl v5.32.0                      2020-08-01            Compress::Raw::Lzma(3)