Ruby/zlib version 0.3.0

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.

Zlib
- Zlib::ZStream
  - Deflate
  - Inflate
- Zlib::Gzip
  - GzipReader
  - GzipWriter

`Zlib`

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

Module Functions:

version: Returns 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_table: Returns the table for calculating CRC checksum.

Exceptions:

The following exceptions are defined in Zlib module. These exceptions are raised when zlib library functions returns with an error status.

Zlib::Error
- 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, Deflate for compression, and Inflate for decompression.

SuperClass:

Object

Methods:

total_in: Returns the total bytes of the input data to the stream.
total_out: Returns 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.
adler: Returns the alder-32 checksum. See zlib.h for details.
close
end: Closes the stream. All operations on the closed stream will raise an exception.
closed?: Returns true if the stream closed.
reset: Resets and initializes the stream. All buffered data in the stream are discarded.
finish: Finishes and flushes the stream and returns all buffered data.
finished?: Returns true if the stream is finished.
flush_out: Flushes the internal output buffer and returns all the data in that buffer.

Constants:

BINARY
ASCII
UNKNOWN: The data types which data_type method returns.

`Deflate`

The class for compressing string data.

SuperClass:

Zlib::ZStream

Class Methods:

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.

Methods:

clone

dup

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

Constants:

NO_COMPRESSION
BEST_SPEED
BEST_COMPRESSION
DEFAULT_COMPRESSION: The compression levels which are an argument of deflate or new.
NO_FLUSH
SYNC_FLUSH
FULL_FLUSH: The integers to control the output of the deflate stream, which are an argument of deflate.
FILTERED
HUFFMAN_ONLY
DEFAULT_STRATEGY: The integers representing compression methods which are an argument of new or params.

`Inflate`

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

SuperClass:

Zlib::ZStream

Class Methods:

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.

Methods:

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.

finish

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::Gzip`

The abstruct class for handling a gzip formatted compressed file. The operations are defined in the subclasses, GzipReader for reading, and GzipWriter for writing.

SuperClass:

Object

Methods:

close
closed?
to_io: Same as IO.
crc: Returns 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_code: Returns OS code number recorded in the gzip file header.
mtime: Returns last modification time recorded in the gzip file header.

Exceptions:

Zlib::Gzip::Error: A subclass of Zlib::Error. Raised when an error is occured during proceeding the gzip file.

`GzipReader`

The 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

SuperClass:

Zlib::Gzip

Included Modules:

Enumerable

Class Methods:

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.

Methods:

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])

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.

When an reading request is received beyond the end of file. That is, when read, gets, or some other methods returns nil.
When close method is called after the object reaches the end of gzip file.
When unused method is called after the object reaches the end of gzip file.

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.

Constants:

OS_CODE
OS_MSDOS
OS_AMIGA
OS_VMS
OS_UNIX
OS_ATARI
OS_OS2
OS_MACOS
OS_TOPS20
OS_WIN32: The return values of os_code method.

Exceptions:

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.

`GzipWriter`

The 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

SuperClass:

Zlib::Gzip

Class Methods:

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.

Methods:

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)
pos
tell
putc(ch)
puts(obj...)
print(arg...)
printf(format, arg...)
sync
write(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= newstate: Sets 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.