The extension library to use zlib from Ruby. Ruby/zlib also provides the features for accessing gzipped files.
You can modify or redistribute Ruby/zlib in the same manner of Ruby interpreter. The latest version of Ruby/zlib would be found at http://www.blue.sky.or.jp/.
This document is experimental and broken English version. If you find some mistakes or strange expressions (including kidding or unnatural ones) in this document, please let me know for my study. Any comments and suggestions are always welcome.
ZlibZlib is the module which provides
the other features in zlib C library. See zlib.h for function details.
versionReturns the string which represents the version of zlib library.
adler32([string, [adler]])Calculates Alder-32 checksum for string, and returns updated value of alder. If string is omitted, it returns the CRC initial value. If alder is omitted, it assumes that the initial value is given to alder.
crc32([string, [crc]])Calculates CRC checksum for string, and returns updated value of crc. If string is omitted, it returns the CRC initial value. If crc is omitted, it assumes that the initial value is given to crc.
crc_tableReturns the table for calculating CRC checksum.
The following exceptions are defined in Zlib module.
These exceptions are raised when zlib library functions returns
with an error status.
Zlib::Error
Zlib::StreamEndZlib::NeedDictZlib::DataErrorZlib::StreamErrorZlib::MemErrorZlib::BufErrorZlib::VersionErrorZlib::ZStreamThe abstruct class for the stream which handles the compressed data.
The operations are defined in the subclasses,
Deflate for compression, and
Inflate for decompression.
Object
total_inReturns the total bytes of the input data to the stream.
total_outReturns the total bytes of the output data from the stream.
data_type
Guesses the type of the data which have been inputed into the stream.
The returned value is Zlib::ZStream::BINARY,
Zlib::ZStream::ASCII, or Zlib::ZStream::UNKNOWN.
adlerReturns the alder-32 checksum. See zlib.h for details.
closeendCloses the stream. All operations on the closed stream will raise an exception.
closed?Returns true if the stream closed.
resetResets and initializes the stream. All buffered data in the stream are discarded.
finishFinishes and flushes the stream and returns all buffered data.
finished?Returns true if the stream is finished.
flush_outFlushes the internal output buffer and returns all the data in that buffer.
BINARYASCIIUNKNOWN
The data types which data_type
method returns.
DeflateThe class for compressing string data.
deflate(string, [level])
Compresses string.
The avail values of level are
Deflate::NO_COMPRESSION,
Deflate::BEST_SPEED,
Deflate::BEST_COMPRESSION,
Deflate::DEFAULT_COMPRESSION,
and the integer from 0 to 9.
This method is equivalant to the following code:
def deflate(string, level) zstream = Deflate.new(level) zstream << string buf = zstream.finish zstream.close buf end
new([level, [windowBits, [memlevel,
[strategy]]]])
Creates a new deflate stream for compression.
See zlib.h for details of each argument.
If an argument is nil, the default value of that argument is used.
clonedupDuplicates the deflate stream.
deflate(string, [flush])
Inputs string into the deflate stream,
and returns the output from the stream.
If string is nil, finishes and flushes the stream,
just like finish.
Note that the output doesn't always match with the input. All the output matches with all the input just when the stream finished.
The value of flush should be Deflate::NO_FLUSH,
Deflate::SYNC_FLUSH or Deflate::FULL_FLUSH.
See zlib.h for details.
<< string
Inputs string into the deflate stream,
just like deflate,
but returns Deflate object itself.
The output from the stream is preserved in the internal buffer.
The internal buffer is flushed by
deflate,
flush,
finish or
flush_out method.
flush([flush])
This method is equivalant to
deflate('', flush).
If flush is omitted, Deflate::SYNC_FLUSH is used
as flush.
This method is just provided for readability of the Ruby script.
params(level, strategy)Changes the parameters of the deflate stream. See zlib.h for details. The output from the stream by changing the params is preserved in the internal buffer.
set_dictionary(string)
Specifies the dictionary using in the compression.
This method is available only just after
new or
reset method was called.
See zlib.h for details.
NO_COMPRESSIONBEST_SPEEDBEST_COMPRESSIONDEFAULT_COMPRESSION
The compression levels which are an argument of
deflate or
new.
NO_FLUSHSYNC_FLUSHFULL_FLUSH
The integers to control the output of the deflate stream,
which are an argument of deflate.
FILTEREDHUFFMAN_ONLYDEFAULT_STRATEGY
The integers representing compression methods which are an argument of
new or
params.
InflateThe class for decompressing compressed data.
Unlike Deflate,
an instance of this class is not able to duplicate
(clone or dup) itself.
inflate(string)
Decompresses string.
Raises a Zlib::NeedDict exception
if a preset dictionary is needed for decompression.
This method is equivalant to the following code:
def inflate(string) zstream = Inflate.new buf = zstream.inflate(string) zstream.finish zstream.close buf end
new([windowBits])
Creates a new inflate stream for decompression.
See zlib.h for details of the argument.
If windowBits is nil, the default value is used.
inflate(string)
Inputs string into the inflate stream,
and returns the output from the stream.
If string is nil, finishes and flushes the stream,
just like finish.
Note that the output doesn't always match with the input.
All the output matches with all the input
just when finished? returnes
true.
Raises a Zlib::NeedDict exception
if a preset dictionary is needed to decompress.
<< string
Inputs string into the inflate stream,
just like inflate,
but returns Inflate object itself.
The output from the stream is preserved in the internal buffer.
The internal buffer is flushed by
inflate,
finish or
flush_out method.
Finishes the inflate stream. In the case of Inflate,
because the stream finishes itself as soon as it meets the end code of the
compressed data, you need not to call finish method explicitly.
Raises an exception if finish is called when
finished? does not returns true.
Returns the garbage following the compressed data.
set_dictionary(string)
Specifies the decompression dictionary.
This method is available only just after a Zlib::NeedDict
exception was raised.
See zlib.h for details.
sync_point?yet undocumented...
Zlib::GzipThe abstruct class for handling a gzip formatted compressed file.
The operations are defined in the subclasses,
GzipReader for reading, and
GzipWriter for writing.
Object
closeclosed?to_io
Same as IO.
crcReturns CRC value of the uncompressed data.
comment
Returns comments recorded in the gzip file header, or
nil if the comments is not present.
orig_name
Returns original filename recorded in the gzip file header, or
nil if the original filename is not present.
os_codeReturns OS code number recorded in the gzip file header.
mtimeReturns last modification time recorded in the gzip file header.
Zlib::Gzip::Error
A subclass of Zlib::Error.
Raised when an error is occured during proceeding the gzip file.
GzipReaderThe class for reading a gzipped file.
GzipReader should be used to associate an instance of IO class
(or an object which has the same methods as IO has).
f = open('hoge.gz') gz = GzipReader.new(f) print gz.read gz.close
Enumerable
new(io)
Creates a GzipReader object associated with io.
The GzipReader object reads gzipped data from io,
and parses/decompresses them.
At least, io must have read method
that behaves same as read method in IO class.
If the gzip file header is incorrect, raises an
Zlib::Gzip::Error exception.
If new is called with a block,
the block will be executed with a newly created GzipReader object,
just like File::open.
The GzipReader object will be closed automatically after executing the block.
If you want to keep the associated IO object opening,
you may call close method
with an argument in the block explicitly.
open(filename)
Opens a file specified by filename as a gzipped file,
and returns a GzipReader object associated with that file.
Further details of this method are same as
new.
close([flag])
Closes the GzipReader object.
If flag is not true,
close method of the associated IO object is called.
Returns the associated IO object.
each([rs])each_line([rs])each_byteeofeof?gets([rs])getclinenolineno=postellread([length])readcharreadline([rs])readlines([rs])ungetc(char)
Same as IO,
but raises Zlib::Error or
Zlib::Gzip::Error exception
if an error was found in the gzip file.
Note that a gzip file has the checksum of pre-compressed data in its footer.
GzipReader checks all uncompressed data against that checksum
at the following cases, and if failed,
raises NoFooter,
CRCError or
LengthError exception.
rewind
Resets the position of the file pointer to
the point created the GzipReader object.
The associated IO object need to have seek method.
unused
Returns the rest of the data which had read for parsing gzip format, or
nil if the whole gzip file is not parsed yet.
OS_CODEOS_MSDOSOS_AMIGAOS_VMSOS_UNIXOS_ATARIOS_OS2OS_MACOSOS_TOPS20OS_WIN32
The return values of os_code method.
GzipReader::NoFooter
A subclass of Zlib::Gzip::Error.
Raised when gzip file footer has not found.
GzipReader::CRCError
A subclass of Zlib::Gzip::Error.
Raised when the CRC checksum recorded in gzip file footer
is not equivalant to CRC checksum of the actually uncompressed data.
GzipReader::LengthError
A subclass of Zlib::Gzip::Error.
Raised when the data length recorded in gzip file footer
is not equivalant to length of the actually uncompressed data.
GzipWriterThe class for writing a gzipped file.
GzipWriter should be used to associate with an instance of IO
class (or an object which has the same methods as IO has).
f = open('hoge.gz', 'w') gz = GzipWriter.new(f) gz.write 'jugemu jugemu gokou no surikire...' gz.close
new(io, [level,
[strategy]])
Creates a GzipWriter object associated with io.
level and strategy should be same as the arguments of
Deflate::new.
The GzipWriter object writes gzipped data to io.
At least, io must have write method
that behaves same as write method in IO class.
If new is called with a block,
the block will be executed with a newly created GzipWriter object,
just like File::open.
The GzipWriter object will be closed automatically after executing the block.
If you want to keep the associated IO object opening,
you may call close method
with an argument in the block explicitly.
open(filename, [level,
[strategy]])
Opens a file specified by filename for writing
gzip compressed data, and returns a GzipWriter object
associated with that file.
Further details of this method are same as
new.
close([flag])
Writes the gzip file footer and closes the GzipWriter object.
If flag is not true,
close method of the associated IO object is called.
Returns the associated IO object.
<<(str)postellputc(ch)puts(obj...)print(arg...)printf(format, arg...)syncwrite(str)
Same as IO.
flush([flush])
Flushes all the internal buffers of the GzipWriter object.
The meaning of flush is same as one of the argument of
Deflate#deflate.
Deflate::SYNC_FLUSH is used if flush is omitted.
It is no use giving flush Deflate::NO_FLUSH.
sync= newstateSets the `sync' mode of the GzipWriter object. The compression ratio decreases sharply while `sync' mode is true.
mtime= time
Sets last modification time to be stored in the gzip file header.
Zlib::Gzip::Error exception
will be raised if this method is called
after writing method (like write)
was called.
orig_name= filename
Sets original filename to be stored in the gzip file header.
Zlib::Gzip::Error exception
will be raised if this method is called
after writing method (like write)
was called.
comment= string
Sets comments to be stored in the gzip file header.
Zlib::Gzip::Error exception
will be raised if this method is called
after writing method (like write)
was called.