Ruby/zlib version 0.5.0

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

Ruby/zlib は Ruby と同じ条件で変更/配布することができます。 Ruby/zlib の最新版は <URL:http://www.blue.sky.or.jp/> から 入手できます。

Ruby/zlib に対するご意見、バグレポート等は ruby-list ML, ruby-dev ML, ruby-ext ML, ruby-talk ML, 又は <URL:mailto:katsu@blue.sky.or.jp> までお願いします。

Zlib

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

モジュール関数:

Zlib.version

zlib ライブラリのバージョンを表す文字列を返します。

Zlib.adlar32([string[, adlar]])

string の Adler-32 チェックサムを計算し、adler を 更新した値を返します。string が省略された場合は Adler-32 チェックサムの初期値を返します。adler が 省略された場合は adler に初期値が与えらたものとして 計算します。

Zlib.crc32([string[, crc]])

string の CRC チェックサムを計算し、crc を 更新した値を返します。string が省略された場合は CRC チェックサムの初期値を返します。crc が 省略された場合は crc に初期値が与えらたものとして 計算します。

Zlib.crc_table

CRC チェックサムの計算に用いるテーブルを配列で返します。

定数:

Zlib::VERSION

zlib.h のバージョンを表す文字列。

Zlib::BINARY
Zlib::ASCII
Zlib::UNKNOWN

Zlib::ZStream#data_type の返す、データタイプを表す整数。

Zlib::NO_COMPRESSION
Zlib::BEST_SPEED
Zlib::BEST_COMPRESSION
Zlib::DEFAULT_COMPRESSION

Zlib::Deflate.new や Zlib::Deflate#deflate 等に渡す、 圧縮レベルを表す整数。

Zlib::FILTERED
Zlib::HUFFMAN_ONLY
Zlib::DEFAULT_STRATEGY

Zlib::Deflate.new や Zlib::Deflate#params に渡す、 圧縮方法を表す整数。

Zlib::DEF_MEM_LEVEL
Zlib::MAX_MEM_LEVEL

Zlib::Deflate.new 等に渡す、memory level を表す整数。

Zlib::MAX_WBITS

Zlib::Deflate.new や Zlib::Inflate.new での windowBits のデフォルト値。

Zlib::NO_FLUSH
Zlib::SYNC_FLUSH
Zlib::FULL_FLUSH
Zlib::FINISH

Zlib::Deflate#deflate 等に渡す、ストリームの出力を 制御するための整数。

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

Zlib::GzipFile#os_code メソッドの返す値。

Zlib::Error

Ruby/zlib の発行する全ての例外のスーパークラス。

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

スーパークラス:

Zlib::ZStream

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

Zlib::ZStream オブジェクトは、ストリーム (struct zstream) の 入力側 (next_in) と出力側 (next_out) にそれぞれ可変長の バッファを持ちます。以下、入力側のバッファを「入力バッファ」、 出力側のバッファを「出力バッファ」と呼びます。

Zlib::ZStream オブジェクトに入力されたデータは、一旦入力バッファの 末尾にストアされた後、ストリームからの出力がなくなるまで (処理後 avail_out > 0 となるまで) 入力バッファの先頭から順に処理されます。 処理の間、出力バッファは全出力を保持するために必要に応じて自動的に 確保・拡張されます。

いくつかのメソッドは、出力バッファ内のデータを取り出し、 String オブジェクトとして返します。

以上を図示すると次のようになります: 

+================ an instance of Zlib::ZStream ================+
||                                                            ||
||     +--------+          +-------+          +--------+      ||
||  +--| output |<---------|zstream|<---------| input  |<--+  ||
||  |  | buffer |  next_out+-------+next_in   | buffer |   |  ||
||  |  +--------+                             +--------+   |  ||
||  |                                                      |  ||
+===|======================================================|===+
    |                                                      |
    v                                                      |
"output data"                                         "input data"

入力バッファの内容を処理している最中にエラーが発生した場合、 Zlib::Error のサブクラスの例外が発生します。その時、 入力/出力バッファは共に、エラーが発生した時点の状態をそのまま 保持します。

スーパークラス:

クラスメソッド:

Zlib::ZStream.new

Zlib::Deflate.new 及び Zlib::Inflate.new を 参照。

メソッド:

Zlib::ZStream#avail_in

入力バッファに溜っているデータのバイト数を返します。 通常は 0 です。

Zlib::ZStream#avail_out

出力バッファの空き用量をバイト数で返します。 空きは必要な時に動的に確保されるため、通常は 0 です。

Zlib::ZStream#avail_out = size

出力側のバッファに size バイトの空きを確保します。 すでに size バイト以上の空きがある場合、バッファは 縮められます。空きは必要な時に動的に確保されるため、通常 このメソッドを使う必要はありません。

Zlib::ZStream#flush_next_in

入力バッファに残っているデータを強制的に取り出します。

Zlib::ZStream#flush_next_out

出力バッファに残っているデータを強制的に取り出します。

Zlib::ZStream#total_in

ストリームに入力されたデータの総バイト数を返します。

Zlib::ZStream#total_out

ストリームの出力したデータの総バイト数を返します。

Zlib::ZStream#data_type

ストリームに入力されたデータの形式を推測します。 返り値は Zlib::BINARY, Zlib::ASCII, Zlib::UNKNOWN のいずれかです。

Zlib::ZStream#adler

alder-32 チェックサムを返します。

Zlib::ZStream#reset

ストリームの状態をリセットします。 入力/出力バッファ内に残っていたデータは破棄されます。

Zlib::ZStream#finish

ストリームへの入力を終了し、出力バッファをフラッシュします。 より具体的な振る舞いは Zlib::Deflate#finish, Zlib::Inflate#finish を参照して下さい。

Zlib::ZStream#finished?
Zlib::ZStream#stream_end?

ストリームへの入力が終了している時に真を返します。

Zlib::ZStream#close
Zlib::ZStream#end

ストリームを閉じます。 以後、このストリームにアクセスすることはできなくなります。

Zlib::ZStream#closed?
Zlib::ZStream#ended?

ストリームが閉じられている時に真を返します。

Zlib::Deflate

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

スーパークラス:

クラスメソッド:

Zlib::Deflate.deflate(string[, level])

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

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

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

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

メソッド:

Zlib::Deflate#clone

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

Zlib::Deflate#deflate(string[, flush])

string を圧縮ストリームに入力します。処理後、 ストリームからの出力を返します。このメソッドを呼ぶと 出力バッファ及び入力バッファは空になります。 string が nil の場合はストリームへの入力を 終了します。(Zlib::ZStream#finish と同じ)。 flush には Zlib::NO_FLUSH, Zlib::SYNC_FLUSH, Zlib::FULL_FLUSH, Zlib::FINISH のいずれかを指定します。 詳しくは zlib.h を参照して下さい。

Zlib::Deflate#<< string

Zlib::Deflate#deflate と同じように string を 圧縮ストリームに入力しますが、Zlib::Deflate オブジェクト そのものを返します。圧縮ストリームからの出力は、 出力バッファに保存されます。

Zlib::Deflate#flush([flush])

deflate('', flush) と同じです。flush が 省略された時は Zlib::SYNC_FLUSH が使用されます。 このメソッドはスクリプトの可読性のために提供されています。

Zlib::Deflate#finish

圧縮ストリームを終了します。deflate('', Zlib::FINISH) と 同じです。

Zlib::Deflate#params(level, strategy)

圧縮ストリームの設定を変更します。詳しくは zlib.h を 参照して下さい。設定の変更に伴うストリームからの出力は 出力バッファに保存されます。

Zlib::Deflate#set_dictionary(string)

圧縮に用いる辞書を指定します。string を返します。 このメソッドは Zlib::Deflate.new, Zlib::ZStream#reset を呼び出した直後にのみ有効です。詳細は zlib.h を参照して下さい。

Zlib::Inflate

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

スーパークラス:

クラスメソッド:

Zlib::Inflate.inflate(string)

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

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

def inflate(string)
  zstream = Zlib::Inflate.new
  buf = zstream.inflate(string)
  zstream.finish
  zstream.close
  buf
end
Zlib::Inflate.new([windowBits])

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

メソッド:

Zlib::Inflate#inflate(string)

string を展開ストリームに入力します。処理後、 ストリームからの出力を返します。このメソッドを呼ぶと 出力バッファ及び入力バッファは空になります。 string が nil の場合はストリームへの入力を 終了します。(Zlib::ZStream#finish と同じ)。

展開に辞書が必要な場合には Zlib::NeedDict 例外が発生します。 Zlib::Inflate#set_dictionary メソッドで辞書をセットした 後で、空文字列と共にこのメソッドを再度呼び出して下さい。

Zlib::Inflate#<< string

Zlib::Inflate#inflate と同じように string を 展開ストリームに入力しますが、Zlib::Inflate オブジェクト そのものを返します。展開ストリームからの出力は、 出力バッファに保存されます。

Zlib::Inflate#finish

展開ストリームを終了します。 ストリーム内に残っていたデータ (つまり圧縮データの後についていた ゴミデータ) を返します。 Zlib::ZStream#finished? が真でない時に finish を呼ぶと 例外が発生します。

展開ストリームは圧縮データ内に終了コードを発見した時点で 自ら終了するため、明示的に finish を呼ぶ必要は必ずしも ありませんが、このメソッドは圧縮データが正しく終了しているかを 確認するのに便利です。

Zlib::Inflate#set_dictionary(string)

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

Zlib::Inflate#sync(string)

string を入力バッファの末尾に追加し、次の full flush point まで読み飛ばします。入力バッファ内に full flush point が存在しない場合は、入力バッファを空にし false を返します。 入力バッファ内に full flush point が見つかった場合は true を返し、残りのデータは入力バッファ内に保持されます。

Zlib::Inflate#sync_point?

What is this?

Zlib::GzipFile

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

IO クラスのインスタンス (又は IO クラスのインスタンスと同じメソッドを 持つオブジェクト) と関連付けて使用します。

スーパークラス:

クラスメソッド:

Zlib::GzipFile.new(io)

Zlib::GzipReader.new 及び Zlib::GzipWriter.new を 参照。

メソッド:

Zlib::GzipFile#closed?
Zlib::GzipFile#to_io

IO クラスの同名メソッドと同じ。

Zlib::GzipFile#close([dont_close_io])

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

Zlib::GzipFile#crc

圧縮されていないデータの CRC 値を返します。

Zlib::GzipFile#level

圧縮レベルを返します。

Zlib::GzipFile#mtime

gzip ファイルのヘッダーに記録されている最終更新時間を返します。

Zlib::GzipFile#os_code

gzip ファイルのヘッダーに記録されている OS コード番号を返します。

Zlib::GzipFile#orig_name

gzip ファイルのヘッダーに記録されている元ファイル名を返します。 ファイル名が記録されていない場合は nil を返します。

Zlib::GzipFile#comment

gzip ファイルのヘッダーに記録されているコメントを返します。 コメントが存在しない場合は nil を返します。

Zlib::GzipFile#sync
Zlib::GzipFile#sync= flag

IO クラスと同じ。flag が真の時、関連付けられている IO オブジェクトが flush メソッドを持っていなければなりません。 また、true にすると圧縮率が著しく低下します。

Zlib::GzipFile::Error

gzip ファイルを処理している間にエラーが生じた時に発生する全ての例外の スーパークラス。

Zlib::GzipFile::NoFooter

gzip ファイルにフッターが無い時に発生します。

Zlib::GzipFile::CRCError

フッターに記録されている CRC 値と実際に展開したデータの CRC 値が異なる時に発生します。

Zlib::GzipFile::LengthError

フッターに記録されているデータ長と実際に展開したデータの 長さが異なる時に発生します。

スーパークラス:

Zlib::GzipReader

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

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)
Zlib::GzipReader.new(io) {|gz| ... }

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

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

ブロックを指定して呼び出した場合は、File.open と同じように GzipReader オブジェクトを与えられてブロックが実行されます。 ブロックの実行が終了すると、GzipReader オブジェクトは自動的に クローズされます。関連付けられている IO オブジェクトまで クローズしたくない時は、ブロック中で引数つきの Zlib::GzipFile#close メソッドを明示的に呼び出して下さい。

Zlib::GzipReader.open(filename)
Zlib::GzipReader.open(filename) {|gz| ... }

filename で指定されるファイルを gzip ファイルとして オープンします。GzipReader オブジェクトを返します。 その他詳細は Zlib::GzipReader.new と同じです。

メソッド:

Zlib::GzipReader#eof
Zlib::GzipReader#eof?

圧縮データの終端に達した場合真を返します。 フッターが読み込まれていなくても真を返すことに注意して下さい。

Zlib::GzipReader#pos
Zlib::GzipReader#tell

現在までに展開したデータの長さの合計を返します。 ファイルポインタの位置ではないことに注意して下さい。

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)

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

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

Zlib::GzipReader#rewind

ファイルポインタを Zlib::GzipReader.new を呼び出した直後の 時点に戻します。関連付けられている IO オブジェクトに seek メソッドが定義されている必要があります。

Zlib::GzipReader#unused

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

Zlib::GzipWriter

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

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

なお、Ruby の finalizer の制約のため、GzipWriter オブジェクトは必ず Zlib::GzipWriter#close 等を用いてクローズしてください。 そうしなければフッターを書き出すことができず、壊れた gzip ファイルを 生成してしまう可能性があります。

スーパークラス:

クラスメソッド:

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

io と関連付けられた GzipWriter オブジェクトを作成します。 level, strategy は Zlib::Deflate.new と同じです。 GzipWriter オブジェクトは io に gzip 形式のデータを 逐次ライトします。io には少なくとも、IO#write と 同じ動作をする write メソッドが定義されている必要があります。

ブロックを指定して呼び出した場合は、File.open と同じように GzipWriter オブジェクトを与えられてブロックが実行されます。 ブロックの実行が終了すると、GzipWriter オブジェクトは自動的に クローズされます。関連付けられている IO オブジェクトまで クローズしたくない時は、ブロック中で引数つきの Zlib::GzipFile#close メソッドを明示的に呼び出して下さい。

Zlib::GzipWriter.open(filename[, level[, strategy]])
Zlib::GzipWriter.open(filename[, level[, strategy]]) {|gz| ... }

filename で指定されるファイルを gzip 圧縮データの 書き出し用にオープンします。GzipWriter オブジェクトを返します。 その他詳細は Zlib::GzipWriter.new と同じです。

メソッド:

Zlib::GzipWriter#close([dont_close_io])

フッターを書き出し、GzipWriter オブジェクトをクローズします。

注意: Ruby の finalizer の制約のため、GzipWriter オブジェクトは 必ずクローズしてください。そうしなければフッターを書き出すことが できず、壊れた gzip ファイルを生成してしまう可能性があります。

Zlib::GzipWriter#pos
Zlib::GzipWriter#tell

現在までに圧縮したデータの長さの合計を返します。 ファイルポインタの位置ではないことに注意して下さい。

Zlib::GzipWriter#<< str
Zlib::GzipWriter#putc(ch)
Zlib::GzipWriter#puts(obj...)
Zlib::GzipWriter#print(arg...)
Zlib::GzipWriter#printf(format, arg...)
Zlib::GzipWriter#write(str)

IO クラスの同名メソッドと同じ。

Zlib::GzipWriter#flush([flush])

まだ書き出されていないデータをフラッシュします。 flush は Zlib::Deflate#deflate と同じです。 省略時は Zlib::SYNC_FLUSH が使用されます。 flush に Zlib::NO_FLUSH を指定することは無意味です。

Zlib::GzipWriter#mtime= time

gzip ファイルのヘッダーに記録する最終更新時間を指定します。 Zlib::GzipWriter#write 等の書き込み系メソッドを 呼んだ後で指定しようとすると Zlib::GzipFile::Error 例外が 発生します。

Zlib::GzipWriter#orig_name= filename

gzip ファイルのヘッダーに記録する元ファイル名を指定します。 Zlib::GzipWriter#write 等の書き込み系メソッドを 呼んだ後で指定しようとすると Zlib::GzipFile::Error 例外が 発生します。

Zlib::GzipWriter#comment= string

gzip ファイルのヘッダーに記録するコメントを指定します。 Zlib::GzipWriter#write 等の書き込み系メソッドを 呼んだ後で指定しようとすると Zlib::GzipFile::Error 例外が 発生します。

0.4.0 からの変更点

全体的に書き換えてます。これで全部…だといいなぁ(汗::