Ruby/zlib is an 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 <URL:http://www.blue.sky.or.jp/>[外部].
Any comments and suggestions are always welcome. Please send them to ruby-list ML, ruby-ext ML, ruby-talk ML, or the author's mail address <URL:mailto:katsu@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.
Zlib is the module which provides the other features in zlib C library. See zlib.h for detail of each module function.
Zlib.zlib_versionReturns the string which represents the version of zlib library.
Zlib.adler32([string[, adler]])Calculates Alder-32 checksum for string, and returns updated value of alder. If string is omitted, it returns the Adler-32 initial value. If alder is omitted, it assumes that the initial value is given to alder.
Zlib.crc32([string[, crc]])Calculates CRC checksum for string, and returns updated value of crc. If string is omitted, it returns the CRC initial value. crc is omitted, it assumes that the initial value is given to crc.
Zlib.crc_tableReturns the table for calculating CRC checksum as an array.
Zlib::VERSIONThe Ruby/zlib version string.
Zlib::ZLIB_VERSIONThe string which represents the version of zlib.h.
Zlib::BINARY
Zlib::ASCII
Zlib::UNKNOWNThe integers representing data types which Zlib::ZStream#data_type method returns.
Zlib::NO_COMPRESSION
Zlib::BEST_SPEED
Zlib::BEST_COMPRESSION
Zlib::DEFAULT_COMPRESSIONThe integers representing compression levels which are an argument for Zlib::Deflate.new, Zlib::Deflate#deflate, and so on.
Zlib::FILTERED
Zlib::HUFFMAN_ONLY
Zlib::DEFAULT_STRATEGYThe integers representing compression methods which are an argument for Zlib::Deflate.new and Zlib::Deflate#params.
Zlib::DEF_MEM_LEVEL
Zlib::MAX_MEM_LEVELThe integers representing memory levels which are an argument for Zlib::Deflate.new, Zlib::Deflate#params, and so on.
Zlib::MAX_WBITSThe default value of windowBits which is an argument for Zlib::Deflate.new and Zlib::Inflate.new.
Zlib::NO_FLUSH
Zlib::SYNC_FLUSH
Zlib::FULL_FLUSH
Zlib::FINISHThe integers to control the output of the deflate stream, which are an argument for Zlib::Deflate#deflate and so on.
Zlib::OS_CODE
Zlib::OS_MSDOS
Zlib::OS_AMIGA
Zlib::OS_VMS
Zlib::OS_UNIX
Zlib::OS_VMCMS
Zlib::OS_ATARI
Zlib::OS_OS2
Zlib::OS_MACOS
Zlib::OS_ZSYSTEM
Zlib::OS_CPM
Zlib::OS_TOPS20
Zlib::OS_WIN32
Zlib::OS_QDOS
Zlib::OS_RISCOS
Zlib::OS_UNKNOWNThe return values of Zlib::GzipFile#os_code method.
The superclass for all exceptions raised by Ruby/zlib.
The following exceptions are defined as subclasses of Zlib::Error. These exceptions are raised when zlib library functions return with an error status.
The abstract class for the stream which handles the compressed data. The operations are defined in the subclasses, Zlib::Deflate for compression, and Zlib::Inflate for decompression.
An instance of Zlib::ZStream has one stream (struct zstream) and two variable-length buffers which associated to the input (next_in) of the stream and the output (next_out) of the stream. In this document, "input buffer" means the buffer for input, and "output buffer" means the buffer for output.
Data inputed into an instance of Zlib::ZStream are temporally stored into the end of input buffer, and then data in input buffer are processed from the beginning of the buffer until no more output from the stream is produced (i.e. until avail_out > 0 after processing). During processing, output buffer is allocated and expanded automatically to hold all output data.
Some particular instance methods consume the data in output buffer and return them as a String.
Here is an ascii art for describing above:
+================ an instance of Zlib::ZStream ================+
|| ||
|| +--------+ +-------+ +--------+ ||
|| +--| output |<---------|zstream|<---------| input |<--+ ||
|| | | buffer | next_out+-------+next_in | buffer | | ||
|| | +--------+ +--------+ | ||
|| | | ||
+===|======================================================|===+
| |
v |
"output data" "input data"
If an error is occurred during processing input buffer, an exception which is a subclass of Zlib::Error is raised. At that time, both input and output buffer keeps their conditions at the time when the error is occurred.
Zlib::ZStream.newSee Zlib::Deflate.new and Zlib::Inflate.new.
Zlib::ZStream#avail_inReturns bytes of data in input buffer. Normally, returns 0.
Zlib::ZStream#avail_outReturns bytes of free spaces in output buffer. Because the free spaces are allocated automatically, this method returns 0 normally.
Zlib::ZStream#avail_out = sizeAllocates free spaces of size bytes in output buffer. If there are more than size bytes spaces in the buffer, the buffer is truncated. Because the free spaces are allocated automatically, you usually need not to use this method.
Zlib::ZStream#flush_next_inFlushes input buffer and returns all data in that buffer.
Zlib::ZStream#flush_next_outFlushes output buffer and returns all data in that buffer.
Zlib::ZStream#total_inReturns the total bytes of the input data to the stream.
Zlib::ZStream#total_outReturns the total bytes of the output data from the stream.
Zlib::ZStream#data_typeGuesses the type of the data which have been inputed into the stream. The returned value is either Zlib::BINARY, Zlib::ASCII, or Zlib::UNKNOWN.
Zlib::ZStream#adlerReturns the alder-32 checksum.
Zlib::ZStream#resetResets and initializes the stream. All data in both input and output buffer are discarded.
Zlib::ZStream#finishFinishes the stream and flushes output buffer. See Zlib::Deflate#finish and Zlib::Inflate#finish for detail of the behavior.
Zlib::ZStream#finished?
Zlib::ZStream#stream_end?Returns true if the stream is finished.
Zlib::ZStream#close
Zlib::ZStream#endCloses the stream. All operations on the closed stream will raise an exception.
Zlib::ZStream#closed?
Zlib::ZStream#ended?Returns true if the stream closed.
The class for compressing string data.
Zlib::Deflate.deflate(string[, level])Compresses string. The avail values of level are Zlib::NO_COMPRESSION, Zlib::BEST_SPEED, Zlib::BEST_COMPRESSION, Zlib::DEFAULT_COMPRESSION, and the integer from 0 to 9.
This method is almost equivalent to the following code:
def deflate(string, level) z = Zlib::Deflate.new(level) dst = z.deflate(string, Zlib::FINISH) z.close dst end
Zlib::Deflate.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.
Zlib::Deflate#cloneDuplicates the deflate stream.
Zlib::Deflate#deflate(string[, flush])Inputs string into the deflate stream and returns the output from the stream. Calling this method, both input and output buffer of the stream are flushed. If string is nil, this method finishes the stream, just like Zlib::ZStream#finish. The value of flush should be either Zlib::NO_FLUSH, Zlib::SYNC_FLUSH, Zlib::FULL_FLUSH, or Zlib::FINISH. See zlib.h for details.
Zlib::Deflate#<< stringInputs string into the deflate stream just like Zlib::Deflate#deflate, but returns Zlib::Deflate object itself. The output from the stream is preserved in output buffer.
Zlib::Deflate#flush([flush])This method is equivalent to deflate('', flush).
If flush is omitted, Zlib::SYNC_FLUSH is used
as flush. This method is just provided for
readability of your Ruby script.
Zlib::Deflate#finishFinishes the stream. This method is equivalent to
deflate('', Zlib::FINISH).
Zlib::Deflate#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 output buffer.
Zlib::Deflate#set_dictionary(string)Sets the preset dictionary and returns string. This method is available just only after Zlib::Deflate.new or Zlib::ZStream#reset method was called. See zlib.h for details.
The class for decompressing compressed data. Unlike Zlib::Deflate, an instance of this class is not able to duplicate (clone, dup) itself.
Zlib::Inflate.inflate(string)Decompresses string. Raises a Zlib::NeedDict exception if a preset dictionary is needed for decompression.
This method is almost equivalent to the following code:
def inflate(string) zstream = Zlib::Inflate.new buf = zstream.inflate(string) zstream.finish zstream.close buf end
Zlib::Inflate.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.
Zlib::Inflate#inflate(string)Inputs string into the inflate stream and returns the output from the stream. Calling this method, both input and output buffer of the stream are flushed. If string is nil, this method finishes the stream, just like Zlib::ZStream#finish.
Raises a Zlib::NeedDict exception if a preset dictionary is needed to decompress. Set the dictionary by Zlib::Inflate#set_dictionary and then call this method again with an empty string.
Zlib::Inflate#<< stringInputs string into the inflate stream just like Zlib::Inflate#inflate, but returns Zlib::Inflate object itself. The output from the stream is preserved in output buffer.
Zlib::Inflate#finishFinishes the inflate stream and returns the garbage following the compressed data. Raises an exception if the stream is not finished (i.e. Zlib::ZStream#finished? doesn't returns true).
The inflate stream finishes itself as soon as it meets the end code of the compressed data, you need not to call this method explicitly. However, this method is useful for checking whether the data is correctly ended or not.
Zlib::Inflate#set_dictionary(string)Sets the preset dictionary and returns string This method is available just only after a Zlib::NeedDict exception was raised. See zlib.h for details.
Zlib::Inflate#sync(string)Inputs string into the end of input buffer and skips data until a full flush point can be found. If the point is found in the buffer, this method flushes the buffer and returns false. Otherwise it returns true and the following data of full flush point is preserved in the buffer.
Zlib::Inflate#sync_point?What is this?
The abstract class for handling a gzip formatted compressed file. The operations are defined in the subclasses, Zlib::GzipReader for reading, and Zlib::GzipWriter for writing.
GzipReader should be used with associating an instance of IO class (or an object which has the same methods as IO has).
Zlib::GzipFile.new(args...)See Zlib::GzipReader.new and Zlib::GzipWriter.new.
Zlib::GzipFile.wrap(args...) {|gz| ... }Zlib::GzipFile.open(args...) {|gz| ... }Zlib::GzipFile#closed?
Zlib::GzipFile#to_ioSame as IO.
Zlib::GzipFile#closeCloses the GzipFile object. This method calls close method of the associated IO object. Returns the associated IO object.
Zlib::GzipFile#finishCloses the GzipFile object. Unlike Zlib::GzipFile#close, this method never calls close method of the associated IO object. Returns the associated IO object.
Zlib::GzipFile#crcReturns CRC value of the uncompressed data.
Zlib::GzipFile#levelReturns compression level.
Zlib::GzipFile#mtimeReturns last modification time recorded in the gzip file header.
Zlib::GzipFile#os_codeReturns OS code number recorded in the gzip file header.
Zlib::GzipFile#orig_nameReturns original filename recorded in the gzip file header, or nil if original filename is not present.
Zlib::GzipFile#commentReturns comments recorded in the gzip file header, or nil if the comments is not present.
Zlib::GzipFile#sync
Zlib::GzipFile#sync= flagSame as IO. If flag is true, the associated IO object must respond to flush method. While `sync' mode is true, the compression ratio decreases sharply.
The superclass for all exceptions raised during processing a gzip file.
The following exceptions are defined as subclasses of Zlib::GzipFile::Error.
Raised when gzip file footer has not found.
Raised when the CRC checksum recorded in gzip file footer is not equivalent to CRC checksum of the actually uncompressed data.
Raised when the data length recorded in gzip file footer is not equivalent to length of the actually uncompressed data.
The class for reading a gzipped file. GzipReader should be used with associating an instance of IO class (or an object which has the same methods as IO has).
Zlib::GzipReader.open('hoge.gz') {|gz|
print gz.read
}
f = File.open('hoge.gz')
gz = Zlib::GzipReader.new(f)
print gz.read
gz.close
Zlib::GzipReader.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::GzipFile::Error exception.
Zlib::GzipReader.wrap(io) {|gz| ... }Creates a GzipReader object associated with io, and executes the block with the 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 Zlib::GzipFile#finish method in the block.
Zlib::GzipReader.open(filename)
Zlib::GzipReader.open(filename) {|gz| ... }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 Zlib::GzipReader.new and ZLib::GzipReader.wrap.
Zlib::GzipReader#eof
Zlib::GzipReader#eof?Returns true if the object reaches the end of compressed data. Note that eof? does not return true when reaches the end of file.
Zlib::GzipReader#pos
Zlib::GzipReader#tellReturns the total bytes of data decompressed until now. Not that it does not the position of file pointer.
Zlib::GzipReader#each([rs])
Zlib::GzipReader#each_line([rs])
Zlib::GzipReader#each_byte([rs])
Zlib::GzipReader#gets([rs])
Zlib::GzipReader#getc
Zlib::GzipReader#lineno
Zlib::GzipReader#lineno=
Zlib::GzipReader#read([length])
Zlib::GzipReader#readchar
Zlib::GzipReader#readline([rs])
Zlib::GzipReader#readlines([rs])
Zlib::GzipReader#ungetc(char)Same as IO, but raises Zlib::Error or Zlib::GzipFile::Error exception if an error was found in the gzip file.
Be careful of the footer of gzip file. 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 Zlib::GzipFile::NoFooter, Zlib::GzipFile::CRCError, or Zlib::GzipFile::LengthError exception.
Zlib::GzipReader#rewindResets the position of the file pointer to the point created the GzipReader object. The associated IO object need to respond to seek method.
Zlib::GzipReader#unusedReturns the rest of the data which had read for parsing gzip format, or nil if the whole gzip file is not parsed yet.
The class for writing a gzipped file. GzipWriter should be used with associate with an instance of IO class (or an object which has the same methods as IO has).
Zlib::GzipWriter.open('hoge.gz') {|gz|
gz.write 'jugemu jugemu gokou no surikire...'
}
f = File.open('hoge.gz', 'w')
gz = Zlib::GzipWriter.new(f)
gz.write 'jugemu jugemu gokou no surikire...'
gz.close
NOTE: Due to the limitation in finalizer of Ruby, you must close explicitly GzipWriter object by Zlib::GzipWriter#close etc. Otherwise, GzipWriter should be not able to write gzip footer and generate broken gzip file.
Zlib::GzipWriter.new(io[, level[, strategy]])Creates a GzipWriter object associated with io. level and strategy should be same as the arguments of Zlib::Deflate.new. The GzipWriter object writes gzipped data to io. At least, io must respond to write method that behaves same as write method in IO class.
Zlib::GzipWriter.wrap(io[, level[, strategy]]) {|gz| ... }Creates a GzipWriter object associated with io, and executes the block with the 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 Zlib::GzipFile#finish method in the block.
Zlib::GzipWriter.open(filename[, level[, strategy]])
Zlib::GzipWriter.open(filename[, level[, strategy]]) {|gz| ... }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 Zlib::GzipWriter.new and Zlib::GzipWriter#wrap.
Zlib::GzipWriter#close
Zlib::GzipWriter#finishCloses the GzipFile object. This method calls close method of the associated IO object. Returns the associated IO object. See Zlib::GzipFile#close and Zlib::GzipFile#finish for the difference between close and finish.
NOTE: Due to the limitation in finalizer of Ruby, you must close GzipWriter object explicitly. Otherwise, GzipWriter should be not able to write gzip footer and generate broken gzip file.
Zlib::GzipWriter#pos
Zlib::GzipWriter#tellReturns the total bytes of data compressed until now. Note that it does not the position of file pointer.
Zlib::GzipWriter#<< str
Zlib::GzipWriter#putc(ch)
Zlib::GzipWriter#puts(obj...)
Zlib::GzipWriter#print(arg...)
Zlib::GzipWriter#printf(format, arg...)
Zlib::GzipWriter#write(str)Same as IO.
Zlib::GzipWriter#flush([flush])Flushes all the internal buffers of the GzipWriter object. The meaning of flush is same as one of the argument of Zlib::Deflate#deflate. Zlib::SYNC_FLUSH is used if flush is omitted. It is no use giving flush Zlib::NO_FLUSH.
Zlib::GzipWriter#mtime= timeSets last modification time to be stored in the gzip file header. Zlib::GzipFile::Error exception will be raised if this method is called after writing method (like Zlib::GzipWriter#write) was called.
Zlib::GzipWriter#orig_name= filenameSets original filename to be stored in the gzip file header. Zlib::GzipFile::Error exception will be raised if this method is called after writing method (like Zlib::GzipWriter#write) was called.
Zlib::GzipWriter#comment= stringSets comments to be stored in the gzip file header. Zlib::GzipFile::Error exception will be raised if this method is called after writing method (like Zlib::GzipWriter#write) was called.
Almost all the code are rewritten. I hope all changes are enumerated below :-)
to avoid segv in finalizer. [ruby-dev:11915][外部]