Module: XZ
- Defined in:
- lib/xz.rb,
lib/xz/version.rb,
lib/xz/lib_lzma.rb
Overview
– The MIT License
Basic liblzma-bindings for Ruby.
Copyright © 2011,2013,2015 Marvin Gülker et al.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ‘Software’), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ++
Defined Under Namespace
Modules: LibLZMA Classes: LZMAError, LZMAStream, Stream, StreamReader, StreamWriter
Constant Summary collapse
- CHUNK_SIZE =
Number of bytes read in one chunk.
4096
- VERSION =
The version of this library.
"0.2.3".freeze
Class Method Summary collapse
-
.compress(str, compression_level = 6, check = :crc64, extreme = false) ⇒ Object
Compresses arbitrary data using the XZ algorithm.
-
.compress_file(in_file, out_file, compression_level = 6, check = :crc64, extreme = false) ⇒ Object
Compresses
in_file
and writes the result toout_file
. -
.compress_stream(io, compression_level = 6, check = :crc64, extreme = false, &block) ⇒ Object
(also: encode_stream)
call-seq: compress_stream(io [, compression_level [, check [, extreme ] ] ] ) → a_string compress_stream(io [, compression_level [, check [, extreme ] ] ] ){|chunk| … } → an_integer encode_stream(io [, compression_level [, check [, extreme ] ] ] ) → a_string encode_stream(io [, compression_level [, check [, extreme ] ] ] ){|chunk| … } → an_integer.
-
.decompress(str, memory_limit = LibLZMA::UINT64_MAX, flags = [:tell_unsupported_check]) ⇒ Object
Decompresses data in XZ format.
-
.decompress_file(in_file, out_file, memory_limit = LibLZMA::UINT64_MAX, flags = [:tell_unsupported_check]) ⇒ Object
Decompresses
in_file
and writes the result toout_file
. -
.decompress_stream(io, memory_limit = LibLZMA::UINT64_MAX, flags = [:tell_unsupported_check], &block) ⇒ Object
(also: decode_stream)
call-seq: decompress_stream(io [, memory_limit [, flags ] ] ) → a_string decompress_stream(io [, memory_limit [, flags ] ] ){|chunk| … } → an_integer decode_stream(io [, memory_limit [, flags ] ] ) → a_string decode_stream(io [, memory_limit [, flags ] ] ){|chunk| … } → an_integer.
-
.deprecate(msg) ⇒ Object
Output a deprecation notice.
-
.disable_deprecation_notices=(bool) ⇒ Object
Force ruby-xz to be silent about deprecations.
Class Method Details
.compress(str, compression_level = 6, check = :crc64, extreme = false) ⇒ Object
Compresses arbitrary data using the XZ algorithm.
Parameters
- str
-
The data to compress.
For the other parameters, see the compress_stream method.
Return value
The compressed data as a BINARY-encoded string.
Example
data = "I love Ruby"
comp = XZ.compress(data) #=> binary blob
Remarks
Don’t use this method for big amounts of data–you may run out of memory. Use compress_file or compress_stream instead.
300 301 302 303 304 |
# File 'lib/xz.rb', line 300 def compress(str, compression_level = 6, check = :crc64, extreme = false) raise(NotImplementedError, "StringIO isn't available!") unless defined? StringIO s = StringIO.new(str) compress_stream(s, compression_level, check, extreme) end |
.compress_file(in_file, out_file, compression_level = 6, check = :crc64, extreme = false) ⇒ Object
Compresses in_file
and writes the result to out_file
.
Parameters
- in_file
-
The path to the file to read from.
- out_file
-
The path of the file to write to. If it exists, it will be overwritten.
For the other parameters, see the ::compress_stream method.
Return value
The number of bytes written, i.e. the size of the archive.
Example
XZ.compress("myfile.txt", "myfile.txt.xz")
XZ.compress("myarchive.tar", "myarchive.tar.xz")
Remarks
This method is safe to use with big files, because files are not loaded into memory completely at once.
269 270 271 272 273 274 275 276 277 |
# File 'lib/xz.rb', line 269 def compress_file(in_file, out_file, compression_level = 6, check = :crc64, extreme = false) File.open(in_file, "rb") do |i_file| File.open(out_file, "wb") do |o_file| compress_stream(i_file, compression_level, check, extreme) do |chunk| o_file.write(chunk) end end end end |
.compress_stream(io, compression_level = 6, check = :crc64, extreme = false, &block) ⇒ Object Also known as: encode_stream
call-seq:
compress_stream(io [, compression_level [, check [, extreme ] ] ] ) → a_string
compress_stream(io [, compression_level [, check [, extreme ] ] ] ){|chunk| ... } → an_integer
encode_stream(io [, compression_level [, check [, extreme ] ] ] ) → a_string
encode_stream(io [, compression_level [, check [, extreme ] ] ] ){|chunk| ... } → an_integer
Compresses a stream of data into XZ-compressed data.
Parameters
- io
-
The IO to read the data from. Must be opened for reading.
- compression_level (6)
-
Compression strength. Higher values indicate a smaller result, but longer compression time. Maximum is 9.
- check (:crc64)
-
The checksum algorithm to use for verifying the data inside the archive. Possible values are:
-
:none
-
:crc32
-
:crc64
-
:sha256
-
- extreme (false)
-
Tries to get the last bit out of the compression. This may succeed, but you can end up with very long computation times.
- chunk (Block argument)
-
One piece of compressed data.
Return value
If a block was given, returns the number of bytes written. Otherwise, returns the compressed data as a BINARY-encoded string.
Example
data = File.read("file.txt")
i = StringIO.new(data)
XZ.compress_stream(i) #=> Some binary blob
i.rewind
str = ""
XZ.compress_stream(i, 4, :sha256){|c| str << c} #=> 123
str #=> Some binary blob
Remarks
The block form is much better on memory usage, because it doesn’t have to load everything into RAM at once. If you don’t know how big your data gets or if you want to compress much data, use the block form. Of course you shouldn’t store the data your read in RAM then as in the example above.
217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 |
# File 'lib/xz.rb', line 217 def compress_stream(io, compression_level = 6, check = :crc64, extreme = false, &block) raise(ArgumentError, "Invalid compression level!") unless (0..9).include?(compression_level) raise(ArgumentError, "Invalid checksum specified!") unless [:none, :crc32, :crc64, :sha256].include?(check) compression_level |= LibLZMA::LZMA_PRESET_EXTREME if extreme stream = LZMAStream.new res = LibLZMA.lzma_easy_encoder(stream.pointer, compression_level, LibLZMA::LZMA_CHECK[:"lzma_check_#{check}"]) LZMAError.raise_if_necessary(res) res = "" res.encode!(Encoding::BINARY) if block_given? res = lzma_code(io, stream, &block) else lzma_code(io, stream){|chunk| res << chunk} end LibLZMA.lzma_end(stream.pointer) block_given? ? stream[:total_out] : res end |
.decompress(str, memory_limit = LibLZMA::UINT64_MAX, flags = [:tell_unsupported_check]) ⇒ Object
Decompresses data in XZ format.
Parameters
- str
-
The data to decompress.
For the other parameters, see the decompress_stream method.
Return value
The decompressed data as a BINARY-encoded string.
Example
comp = File.open("data.xz", "rb"){|f| f.read}
data = XZ.decompress(comp) #=> "I love Ruby"
Remarks
Don’t use this method for big amounts of data–you may run out of memory. Use decompress_file or decompress_stream instead.
327 328 329 330 331 |
# File 'lib/xz.rb', line 327 def decompress(str, memory_limit = LibLZMA::UINT64_MAX, flags = [:tell_unsupported_check]) raise(NotImplementedError, "StringIO isn't available!") unless defined? StringIO s = StringIO.new(str) decompress_stream(s, memory_limit, flags) end |
.decompress_file(in_file, out_file, memory_limit = LibLZMA::UINT64_MAX, flags = [:tell_unsupported_check]) ⇒ Object
Decompresses in_file
and writes the result to out_file
.
Parameters
- in_file
-
The path to the file to read from.
- out_file
-
The path of the file to write to. If it exists, it will be overwritten.
For the other parameters, see the decompress_stream method.
Return value
The number of bytes written, i.e. the size of the uncompressed data.
Example
XZ.decompres("myfile.txt.xz", "myfile.txt")
XZ.decompress("myarchive.tar.xz", "myarchive.tar")
Remarks
This method is safe to use with big files, because files are not loaded into memory completely at once.
359 360 361 362 363 364 365 366 367 |
# File 'lib/xz.rb', line 359 def decompress_file(in_file, out_file, memory_limit = LibLZMA::UINT64_MAX, flags = [:tell_unsupported_check]) File.open(in_file, "rb") do |i_file| File.open(out_file, "wb") do |o_file| decompress_stream(i_file, memory_limit, flags) do |chunk| o_file.write(chunk) end end end end |
.decompress_stream(io, memory_limit = LibLZMA::UINT64_MAX, flags = [:tell_unsupported_check], &block) ⇒ Object Also known as: decode_stream
call-seq:
decompress_stream(io [, memory_limit [, flags ] ] ) → a_string
decompress_stream(io [, memory_limit [, flags ] ] ){|chunk| ... } → an_integer
decode_stream(io [, memory_limit [, flags ] ] ) → a_string
decode_stream(io [, memory_limit [, flags ] ] ){|chunk| ... } → an_integer
Decompresses a stream containing XZ-compressed data.
Parameters
- io
-
The IO to read from. It must be opened for reading.
- memory_limit (
UINT64_MAX
) -
If not XZ::LibLZMA::UINT64_MAX, makes liblzma use no more memory than
memory_limit
bytes. - flags (
[:tell_unsupported_check]
) -
Additional flags passed to liblzma (an array). Possible flags are:
- :tell_no_check
-
Spit out a warning if the archive hasn’t an integrity checksum.
- :tell_unsupported_check
-
Spit out a warning if the archive has an unsupported checksum type.
- :concatenated
-
Decompress concatenated archives.
- chunk (Block argument)
-
One piece of decompressed data.
Return value
If a block was given, returns the number of bytes written. Otherwise, returns the decompressed data as a BINARY-encoded string.
Example
data = File.open("archive.xz", "rb"){|f| f.read}
io = StringIO.new(data)
XZ.decompress_stream(io) #=> "I AM THE DATA"
io.rewind
str = ""
XZ.decompress_stream(io, XZ::LibLZMA::UINT64_MAX, [:tell_no_check]){|c| str << c} #=> 13
str #=> "I AM THE DATA"
Remarks
The block form is much better on memory usage, because it doesn’t have to load everything into RAM at once. If you don’t know how big your data gets or if you want to decompress much data, use the block form. Of course you shouldn’t store the data you read in RAM then as in the example above.
128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 |
# File 'lib/xz.rb', line 128 def decompress_stream(io, memory_limit = LibLZMA::UINT64_MAX, flags = [:tell_unsupported_check], &block) raise(ArgumentError, "Invalid memory limit set!") unless memory_limit > 0 && memory_limit <= LibLZMA::UINT64_MAX # bit-or all flags allflags = flags.inject(0) do |val, flag| flag = LibLZMA::LZMA_DECODE_FLAGS[flag] || raise(ArgumentError, "Unknown flag #{flag}!") val | flag end stream = LZMAStream.new res = LibLZMA.lzma_stream_decoder(stream.pointer, memory_limit, allflags) LZMAError.raise_if_necessary(res) res = "" res.encode!(Encoding::BINARY) if block_given? res = lzma_code(io, stream, &block) else lzma_code(io, stream){|chunk| res << chunk} end LibLZMA.lzma_end(stream.pointer) block_given? ? stream[:total_out] : res end |
.deprecate(msg) ⇒ Object
Output a deprecation notice.
62 63 64 65 66 67 68 |
# File 'lib/xz.rb', line 62 def deprecate(msg) # :nodoc: @disable_deprecation_notices ||= false unless @disable_deprecation_notices $stderr.puts("DEPRECATION NOTICE: #{msg}\n#{caller.drop(1).join("\n\t")}") end end |
.disable_deprecation_notices=(bool) ⇒ Object
Force ruby-xz to be silent about deprecations. Using this is discouraged so that you are aware of upcoming changes to the API. However, if your standard error stream is closed, outputting the deprecation notices might result in an exception, so this method allows you to surpress these notices. Ensure you read the HISTORY.rdoc file carefully instead.
57 58 59 |
# File 'lib/xz.rb', line 57 def disable_deprecation_notices=(bool) @disable_deprecation_notices = bool end |