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

Compression

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

Uncompression

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

Filters

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

Misc

553   my $version = Compress::Raw::Lzma::lzma_version_number();
554       Returns the version of the underlying lzma library.
555
556   my $version = Compress::Raw::Lzma::lzma_version_string();
557       Returns the version of the underlying lzma library.
558
559       TODO - more here
560

Constants

562       The following lzma constants are exported by this module
563
564       TODO - more here
565

AUTHOR

581       This module was written by Paul Marquess, pmqs@cpan.org.
582

MODIFICATION HISTORY

584       See the Changes file.
585

COPYRIGHT AND LICENSE

587       Copyright (c) 2005-2010 Paul Marquess. All rights reserved.
588
589       This program is free software; you can redistribute it and/or modify it
590       under the same terms as Perl itself.
591
592
593
594perl v5.12.1                      2010-07-24            Compress::Raw::Lzma(3)