Ruby/zlib version 0.1.0

zlib を Ruby から使うための拡張ライブラリ。 gzip ファイルの読み書きもサポートします。

Ruby/zlib は Ruby と同じ条件で配布することができます。

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

Zlib

zlib ライブラリに含まれている雑多な機能を提供するモジュール。各関数の詳細は zlib.h を参照して下さい。

モジュール関数:

version: zlib ライブラリのバージョンを表す文字列を返します。
adler32([string, [adler]]): string の Adler-32 チェックサムを計算し、 adler を更新した値を返します。 string が省略された場合は、Adler-32 チェックサムの初期値を返します。 adler が省略された場合は、adler に初期値が与えらたものとして計算します。
crc32([string, [crc]]): string の CRC チェックサムを計算し、 crc を更新した値を返します。 string が省略された場合は、CRC チェックサムの初期値を返します。 crc が省略された場合は、crc に初期値が与えらたものとして計算します。
crc_table: CRC チェックサムの計算に用いるテーブルを返します。

例外クラス:

以下の例外が定義されています。それぞれ zlib ライブラリ関数の返すエラーと対応しています。

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

Zlib::ZStream

圧縮データを扱うストリームを表す抽象クラス。具体的な圧縮/展開の操作は、それぞれサブクラスの Deflate, Inflate で定義されています。

スーパークラス:

Object

メソッド:

total_in: ストリームに入力されたデータの総バイト数を返します。
total_out: ストリームの出力したデータの総バイト数を返します。
data_type: ストリームに入力されたデータの形式を推測します。返り値は Zlib::ZStream::BINARY, Zlib::ZStream::ASCII, Zlib::ZStream::UNKNOWN のいずれかです。
adler: alder-32 チェックサムを返します。詳しくは zlib.h を参照して下さい。
close
end: ストリームを閉じます。以後、このストリームにアクセスすることはできなくなります。
closed?: ストリームが閉じられている時に真を返します。
reset: ストリームの状態をリセットします。ストリーム内に残っていたデータは破棄されます。
finish: ストリームへの入力を終了します。ストリーム内に残っていたデータを返します。
finished?: ストリームへの入力が終了している時に真を返します。

定数:

BINARY
ASCII
UNKNOWN: data_type の返す、データタイプを表す整数。

Deflate

入力データを圧縮するストリームのクラス。

スーパークラス:

Zlib::ZStream

クラスメソッド:

deflate(string, [level])

string を圧縮します。 level の有効な値は Deflate::NO_COMPRESSION, Deflate::BEST_SPEED, Deflate::BEST_COMPRESSION, Deflate::DEFAULT_COMPRESSION 及び 0 から 9 の整数です。

ちなみに、このメソッドは以下のコードと同じです:

def deflate(string, level)
  zstream = Deflate.new(level)
  buf = zstream.deflate(string)
  buf << zstream.finish
  zstream.close
  buf
end

new([level, [windowBits, [memlevel, [strategy]]]])

圧縮ストリームを作成します。各引数の詳細は zlib のヘッダーファイルを参照して下さい。 nil の場合はデフォルトの値を使用します。

メソッド:

clone

圧縮ストリームを複製します。

deflate(string, [flush])

<< string

string を圧縮ストリームに入力します。圧縮ストリームからの出力を返します。 string が nil の場合はストリームへの入力を終了し、ストリーム内に残っていたデータを出力します (finish と同じ)。

入力と出力は必ずしも対応しないことに注意してください。 finish が呼ばれて初めて 全入力と全出力が対応します。

flush には Deflate::NO_FLUSH, Deflate::SYNC_FLUSH, Deflate::FULL_FLUSH のどれかを指定します。詳しくは zlib のヘッダーファイルを参照して下さい。

params(level, strategy)

圧縮ストリームの設定を変更します。詳しくは zlib のヘッダーファイルを参照して下さい。

set_dictionary(string)

圧縮に用いる辞書を指定します。このメソッドは new, reset を呼び出した直後にのみ有効です。詳細は zlib のヘッダーファイルを参照して下さい。

定数:

NO_COMPRESSION
BEST_SPEED
BEST_COMPRESSION
DEFAULT_COMPRESSION: deflate や new に渡す、圧縮レベルを表す整数。
NO_FLUSH
SYNC_FLUSH
FULL_FLUSH: deflate に渡す、ストリームの出力を制御するための整数。
FILTERED
HUFFMAN_ONLY
DEFAULT_STRATEGY: new や params に渡す、圧縮方法を表す整数。

Inflate

入力データを展開するストリームのクラス。 Deflate と違い、このクラスのインスタンスを複製 (clone, dup) することはできません。

スーパークラス:

Zlib::ZStream

クラスメソッド:

inflate(string)

string を展開します。展開に辞書が必要な場合には例外 Zlib::NeedDict が発生します。

ちなみに、このメソッドは以下のコードと同じです:

def inflate(string)
  zstream = Inflate.new
  buf = zstream.inflate(string)
  zstream.finish
  zstream.close
  buf
end

new([windowBits])

展開ストリームを作成します。引数の詳細は zlib のヘッダーファイルを参照して下さい。 nil の場合はデフォルトの値を使用します。

メソッド:

inflate(string)

<< string

string を展開ストリームに入力します。展開ストリームからの出力を返します。 string が nil の場合はストリームへの入力を終了し、ストリーム内に残っていたデータを出力します (finish と同じ)。

入力と出力は必ずしも対応しないことに注意してください。 finished? が真になった時に初めて全入力と全出力が対応します。

展開に辞書が必要な場合には例外 Zlib::NeedDict が発生します。

finish

展開ストリームを終了します。Inflate の場合、圧縮データ内に終了コードを発見した時点でストリームが終了するため finish を呼ぶ必要は必ずしもありません。 finished? が真でない時に finish を呼ぶと例外が発生します。

圧縮データの後についていたゴミデータを返します。

set_dictionary(string)

展開に用いる辞書を指定します。このメソッドは例外 Zlib::NeedDict が発生した直後のみ有効です。詳細は zlib のヘッダーファイルを参照して下さい。

sync_point?

undocumented yet...

Zlib::Gzip

gzip 形式の圧縮ファイルを扱う抽象クラス。具体的な読み込み/書き込み操作は、それぞれサブクラスの GzipReader, GzipWriter で定義されています。

スーパークラス:

Object

メソッド:

close
closed?
to_io: IO クラスと同じ。
crc: 未圧縮データの CRC 値を返します。
comment: gzip ファイルのヘッダーに記録されているコメントを返します。ファイルが存在しない場合は nil を返します。
orig_name: gzip ファイルのヘッダーに記録されている元ファイル名を返します。ファイル名が記録されていない場合は nil を返します。
os_code: gzip ファイルのヘッダーに記録されている OS コード番号を返します。
mtime: gzip ファイルのヘッダーに記録されている最終更新時間を返します。

例外クラス:

Zlib::Gzip::Error: Zlib::Error のサブクラス。 gzip ファイルを処理している間にエラーが生じた時に発生します。

GzipReader

gzip 形式の圧縮ファイルを読み込むラッパークラス。 IO クラスのインスタンス (又は IO クラスのインスタンスと同じメソッドを持つオブジェクト) と関連付けて使用します。

f = open('hoge.gz')
gz = GzipReader.new(f)
print gz.read
gz.close

スーパークラス:

Zlib::Gzip

インクルードしているモジュール:

Enumerable

クラスメソッド:

new(io)

io と関連付けられた GzipReader オブジェクトを作成します。GzipReader オブジェクトは io からデータを逐次リードして解析/展開を行います。 io には少なくとも、 IO クラスの read メソッドと同じ動作をする read メソッドが定義されている必要があります。

ヘッダーの解析に失敗した場合 Gzip::Error 例外が発生します。

open(filename)

filename で指定されるファイルを gzip ファイルとしてオープンします。 GzipReader オブジェクトを返します。

メソッド:

close([flag])

GzipReader オブジェクトをクローズします。 flag が真でない時は、関連付けられている IO オブジェクトの close メソッドを呼び出します。関連付けられている IO オブジェクトを返します。

each([rs])

each_line([rs])

readlines([rs])

ungetc(char)

IO クラスと同じですが、 gzip ファイル中にエラーがあった場合 Zlib::Error 例外や Zlib::Gzip::Error 例外が発生します。

また、gzip ファイルのフッターの処理に若干注意する必要があります。

gzip ファイルのフッターには圧縮前データのチェックサムが記録されています。 GzipReader オブジェクトは次の時に展開したデータとフッターの照合を行い、エラーがあった場合は NoFooter, CRCError, LengthError 例外を発生させます。

EOF を越えて読み込み要求を受けた時。すなわち read, gets メソッド等が nil を返す時。
EOF まで読み込んだ後、close メソッドが呼び出された時。
EOF まで読み込んだ後、unused メソッドが呼び出された時。

rewind

ファイルポインタを GzipReader オブジェクトが作成された時点に戻します。関連付けられている IO オブジェクトに seek メソッドが定義されている必要があります。

unused

gzip フォーマットの解析のために読み込んだ余剰のデータを返します。 gzip ファイルが最後まで解析されていない場合は nil を返します。

定数:

OS_CODE
OS_MSDOS
OS_AMIGA
OS_VMS
OS_UNIX
OS_ATARI
OS_OS2
OS_MACOS
OS_TOPS20
OS_WIN32: os_code メソッドの返す値。

例外クラス:

GzipReader::NoFooter: Zlib::Gzip::Error のサブクラス。 gzip ファイルにフッターが無い時に発生します。
GzipReader::CRCError: Zlib::Gzip::Error のサブクラス。フッターに記録されている CRC 値と実際に展開したデータの CRC 値が異なる時に発生します。
GzipReader::LengthError: Zlib::Gzip::Error のサブクラス。フッターに記録されているデータ長と実際に展開したデータの長さが異なる時に発生します。

GzipWriter

gzip 形式の圧縮ファイルを書き出すラッパークラス。 IO クラスのインスタンス (又は IO クラスのインスタンスと同じメソッドを持つオブジェクト) と関連付けて使用します。

f = open('hoge.gz', 'w')
gz = GzipWriter.new(f)
gz.write 'jugemu jugemu gokou no surikire...'
gz.close

スーパークラス:

Zlib::Gzip

クラスメソッド:

new(io, [level, [strategy]]): io と関連付けられた GzipWriter オブジェクトを作成します。level, strategy は Deflate::new と同じです。 GzipWriter オブジェクトは io に gzip 形式のデータを逐次ライトします。 io には少なくとも、 IO クラスの write メソッドと同じ動作をする write メソッドが定義されている必要があります。
open(filename, [level, [strategy]]): filename で指定されるファイルを gzip 圧縮データの書き出し用にオープンします。 GzipWriter オブジェクトを返します。

メソッド:

close([flag]): フッターを書き出し、GzipWriter オブジェクトをクローズします。 flag が真でない時は、関連付けられている IO オブジェクトの close メソッドを呼び出します。関連付けられている IO オブジェクトを返します。
<<(str)
pos
tell
putc(ch)
puts(obj...)
print(arg...)
printf(format, arg...)
sync
write(str): IO クラスと同じ。
sync= newstate: 出力同期モードを設定します。 true にすると圧縮率が著しく低下します。
mtime= time: gzip ファイルのヘッダーに記録する最終更新時間を指定します。 write 等の書き込み系メソッドを呼んだ後で指定しようとすると Zlib::Gzip::Error 例外が発生します。
orig_name= filename: gzip ファイルのヘッダーに記録する元ファイル名を指定します。 write 等の書き込み系メソッドを呼んだ後で指定しようとすると Zlib::Gzip::Error 例外が発生します。
comment= string: gzip ファイルのヘッダーに記録するコメントを指定します。 write 等の書き込み系メソッドを呼んだ後で指定しようとすると Zlib::Gzip::Error 例外が発生します。