Ruby/zlib version 0.3.0

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

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

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::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?

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

flush_out

ZStream オブジェクトの内部バッファに溜っているデータを 強制的に取り出します。

定数:

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)
  zstream << string
  buf = zstream.finish
  zstream.close
  buf
end
new([level, [windowBits, [memlevel, [strategy]]]])

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

メソッド:

clone

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

deflate(string, [flush])

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

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

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

<< string

deflate と同じですが、 Deflate オブジェクトそのものを返します。 圧縮ストリームからの出力は内部バッファに保存されます。 内部バッファは、deflate, flush, finish, flush_out メソッドによってフラッシュされます。

flush([flush])

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

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 が nil の場合はストリームへの入力を終了し、 ストリーム内に残っていたデータを出力します (finish と同じ)。

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

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

<< string

inflate と同じですが、 Inflate オブジェクトそのものを返します。 展開ストリームからの出力は内部バッファに保存されます。 内部バッファは、inflate, finish, flush_out メソッドによってフラッシュされます。

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 例外が発生します。

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

open(filename)

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

その他詳細は new と同じです。

メソッド:

close([flag])

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

each([rs])
each_line([rs])
each_byte
eof
eof?
gets([rs])
getc
lineno
lineno=
pos
tell
read([length])
readchar
readline([rs])
readlines([rs])
ungetc(char)

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

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

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

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 メソッドが定義されている必要があります。

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

open(filename, [level, [strategy]])

filename で指定されるファイルを gzip 圧縮データの書き出し用に オープンします。 GzipWriter オブジェクトを返します。

その他詳細は new と同じです。

メソッド:

close([flag])

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

<<(str)
pos
tell
putc(ch)
puts(obj...)
print(arg...)
printf(format, arg...)
sync
write(str)

IO クラスと同じ。

flush([flush])

内部バッファをフラッシュします。 flush は Deflate#deflate と同じです。省略時は Deflate::SYNC_FLUSH が使用されます。

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 例外が発生します。

Copyright (C) Ueno Katsuhiro 2000 - All rights reserved.