Ruby/zlib version 0.5.0

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
Changes from 0.4.0

Zlib

Zlib is the module which provides the other features in zlib C library. See zlib.h for detail of each module function.

Module Functions:

Zlib.version: Returns the string which represents the version of zlib library.
Zlib.adlar32([string[, adlar]]): 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_table: Returns the table for calculating CRC checksum as an array.

Constants:

Zlib::VERSION: The string which represents the version of zlib.h.
Zlib::BINARY
Zlib::ASCII
Zlib::UNKNOWN: The integers representing data types which Zlib::ZStream#data_type method returns.
Zlib::NO_COMPRESSION
Zlib::BEST_SPEED
Zlib::BEST_COMPRESSION
Zlib::DEFAULT_COMPRESSION: The 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_STRATEGY: The integers representing compression methods which are an argument for Zlib::Deflate.new and Zlib::Deflate#params.
Zlib::DEF_MEM_LEVEL
Zlib::MAX_MEM_LEVEL: The integers representing memory levels which are an argument for Zlib::Deflate.new, Zlib::Deflate#params, and so on.
Zlib::MAX_WBITS: The 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::FINISH: The 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_ATARI
Zlib::OS_OS
Zlib::OS_MACOS
Zlib::OS_TOPS
Zlib::OS_WIN: The return values of Zlib::GzipFile#os_code method.

Zlib::Error

The superclass for all excpetions 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.

Zlib::StreamEnd
Zlib::NeedDict
Zlib::DataError
Zlib::StreamError
Zlib::MemError
Zlib::BufError
Zlib::VersionError

Zlib::ZStream

The abstruct class for the stream which handles the compressed data. The operations are defined in the subclasses, Zlib::Deflate for compression, and Zlib::Inflate for decpmpression.

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 paticular 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 occured 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 occured.

SuperClass:

Object

Class Methods:

Zlib::ZStream.new: See Zlib::Deflate.new and Zlib::Inflate.new.

Methods:

Zlib::ZStream#avail_in: Returns bytes of data in input buffer. Normally, returns 0.
Zlib::ZStream#avail_out: Returns bytes of free spaces in output buffer. Because the free spaces are allocated automatically, this method returns 0 normally.
Zlib::ZStream#avail_out = size: Allocates 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_in: Flushes input buffer and returns all data in that buffer.
Zlib::ZStream#flush_next_out: Flushes output buffer and returns all data in that buffer.
Zlib::ZStream#total_in: Returns the total bytes of the input data to the stream.
Zlib::ZStream#total_out: Returns the total bytes of the output data from the stream.
Zlib::ZStream#data_type: Guesses 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#adler: Returns the alder-32 checksum.
Zlib::ZStream#reset: Resets and initializes the stream. All data in both input and output buffer are discarded.
Zlib::ZStream#finish: Finishes 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#end: Closes the stream. All operations on the closed stream will raise an exception.
Zlib::ZStream#closed?
Zlib::ZStream#ended?: Returns true if the stream closed.

Zlib::Deflate

The class for compressing string data.

SuperClass:

Zlib::ZStream

Class Methods:

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 almostly equivalant 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.

Methods:

Zlib::Deflate#clone: Duplicates 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#<< string: Inputs 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 equivalant 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#finish: Finishes the stream. This method is equivalant 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.

Zlib::Inflate

The class for decompressing compressed data. Unlike Zlib::Deflate, an instance of this class is not able to duplicate (clone, dup) itself.

SuperClass:

Zlib::ZStream

Class Methods:

Zlib::Inflate.inflate(string)

Decompresses string. Raises a Zlib::NeedDict exception if a preset dictionary is needed for decompression.

This method is almostly equivalant 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.

Methods:

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#<< string

Inputs 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#finish

Finishes 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 thisd 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?

Zlib::GzipFile

The abstruct 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).

SuperClass:

Object

Class Methods:

Zlib::GzipFile.new(io): See Zlib::GzipReader.new and Zlib::GzipWriter.new.

Methods:

Zlib::GzipFile#closed?
Zlib::GzipFile#to_io: Same as IO.
Zlib::GzipFile#close([dont_close_io]): Closes the GzipReader object. If dont_close_io is ommited or not true, close method of the associated IO object is called. Returns the associated IO object.
Zlib::GzipFile#crc: Returns CRC value of the uncompressed data.
Zlib::GzipFile#level: Returns compression level.
Zlib::GzipFile#mtime: Returns last modification time recorded in the gzip file header.
Zlib::GzipFile#os_code: Returns OS code number recorded in the gzip file header.
Zlib::GzipFile#orig_name: Returns original filename recorded in the gzip file header, or nil if original filename is not present.
Zlib::GzipFile#comment: Returns comments recorded in the gzip file header, or nil if the comments is not present.
Zlib::GzipFile#sync
Zlib::GzipFile#sync= flag: Same 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.

Zlib::GzipFile::Error

The superclass for all exceptions raised during processing a gzip file.

The following exceptions are defined as subclasses of Zlib::GzipFile::Error.

Zlib::GzipFile::NoFooter: Raised when gzip file footer has not found.
Zlib::GzipFile::CRCError: Raised when the CRC checksum recorded in gzip file footer is not equivalant to CRC checksum of the actually uncompressed data.
Zlib::GzipFile::LengthError: Raised when the data length recorded in gzip file footer is not equivalant to length of the actually uncompressed data.

SuperClass:

Zlib::Error

Zlib::GzipReader

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

SuperClass:

Zlib::GzipFile

Included Module:

Enumerable

Class Methods:

Zlib::GzipReader.new(io)

Zlib::GzipReader.new(io) {|gz| ... }

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.

If this method 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 explicitly Zlib::GzipFile#close method with an argument 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.

Methods:

Zlib::GzipReader#eof

Zlib::GzipReader#eof?

Returns true if the object reaches the end of ompressed data. Note that eof? does not return true when reaches the end of file.

Zlib::GzipReader#pos

Zlib::GzipReader#tell

Returns 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.

When an reading request is received beyond the end of file (the end of compressed data). That is, when Zlib::GzipReader#read, Zlib::GzipReader#gets, or some other methods for reading returns nil.
When Zlib::GzipFile#close method is called after the object reaches the end of file.
When Zlib::GzipReader#unused method is called after the object reaches the end of file.

Zlib::GzipReader#rewind

Resets 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#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.

Zlib::GzipWriter

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.

SuperClass:

Zlib::GzipFile

Class Methods:

Zlib::GzipWriter.new(io[, level[, strategy]])

Zlib::GzipWriter.new(io[, level[, strategy]]) {|gz| ... }

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.

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 explicitly Zlib::GzipFile#close method with an argument in the block explicitly.

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.

Methods:

Zlib::GzipWriter#close([dont_close_io])

Writes the gzip file footer and closes the GzipWriter object.

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#tell

Returns 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= time

Sets 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= filename

Sets 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= string

Sets 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.

Changes from 0.4.0

Almost all the code are rewritten. I hope all changes are enumerated below :-)

The names of almost classes and some methods are changed. All classes and constants are now defined under module Zlib. The obsoleted names are also available for backward compatibility.
- Classes
  - Deflate -> Zlib::Deflate
  - Inflate -> Zlib::Inflate
  - Zlib::Gzip -> Zlib::GzipFile
  - GzipReader -> Zlib::GzipReader
  - GzipWriter -> Zlib::GzipWriter
  - Zlib::Gzip::Error -> Zlib::GzipFile::Error
  - Zlib::GzipReader::NoFooter -> Zlib::GzipFile::NoFooter
  - Zlib::GzipReader::CRCError -> Zlib::GzipFile::CRCError
  - Zlib::GzipReader::LengthError -> Zlib::GzipFile::LengthError
- Constants
  - Zlib::ZStream::BINARY -> Zlib::BINARY
  - Zlib::ZStream::ASCII -> Zlib::ASCII
  - Zlib::ZStream::UNKNOWN -> Zlib::UNKNOWN
  - Zlib::Deflate::NO_COMPRESSION -> Zlib::NO_COMPRESSION
  - Zlib::Deflate::BEST_SPEED -> Zlib::BEST_SPEED
  - Zlib::Deflate::BEST_COMPRESSION -> Zlib::BEST_COMPRESSION
  - Zlib::Deflate::DEFAULT_COMPRESSION -> Zlib::DEFAULT_COMPRESSION
  - Zlib::Deflate::FILTERED -> Zlib::FILTERED
  - Zlib::Deflate::HUFFMAN_ONLY -> Zlib::HUFFMAN_ONLY
  - Zlib::Deflate::DEFAULT_STRATEGY -> Zlib::DEFAULT_STRATEGY
  - Zlib::Deflate::MAX_WBITS -> Zlib::MAX_WBITS
  - Zlib::Deflate::DEF_MEM_LEVEL -> Zlib::DEF_MEM_LEVEL
  - Zlib::Deflate::MAX_MEM_LEVEL -> Zlib::MAX_MEM_LEVEL
  - Zlib::Deflate::NO_FLUSH -> Zlib::NO_FLUSH
  - Zlib::Deflate::SYNC_FLUSH -> Zlib::SYNC_FLUSH
  - Zlib::Deflate::FULL_FLUSH -> Zlib::FULL_FLUSH
  - Zlib::Inflate::MAX_WBITS -> Zlib::MAX_WBITS
  - Zlib::GzipReader::OS_* -> Zlib::OS_*
- Methods
  - Zlib::ZStream#flush_out -> Zlib::ZStream#flush_next_out
Zlib::Error#next_in method is added.
Made buffer for input (next_in).
Process NeedDict error specially.
Zlib::GzipReader#unused returns nil after closing.
Now you are up to call Zlib::GzipWriter#close explicitly to avoid segv in finalizer. [ruby-dev:11915]
divided intialize from new.
remove sanity checks for arguments for deflateInit2 and inflateInit2.
adapted the behavior of Zlib::GzipWriter#puts to Ruby-1.7.
Made all functions static.