=begin # # zlib.rd.src # # Copyright (C) UENO Katsuhiro 2000-2002 # # $Id: zlib.rd.src,v 1.14 2002/03/13 19:13:14 katsu Exp $ # = Ruby/zlib version 0.5.0 Ruby/zlib は zlib を Ruby から使うための拡張ライブラリです。 gzip ファイルの読み書きもサポートします。 Ruby/zlib は Ruby と同じ条件で変更/配布することができます。 Ruby/zlib の最新版は (()) から入手できます。 Ruby/zlib に対するご意見、バグレポート等は ruby-list ML, ruby-dev ML, ruby-ext ML, ruby-talk ML, 又は (()) までお願いします。 * (()) * (()) * (()) * (()) * (()) * (()) * (()) * (()) * (()) * ((<0.4.0 からの変更点>)) == 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::NO_COMPRESSION --- Zlib::BEST_SPEED --- Zlib::BEST_COMPRESSION --- Zlib::DEFAULT_COMPRESSION (()) や (()) 等に渡す、圧縮レベルを表す整数。 --- Zlib::FILTERED --- Zlib::HUFFMAN_ONLY --- Zlib::DEFAULT_STRATEGY (()) や (()) に渡す、圧縮方法を表す整数。 --- Zlib::DEF_MEM_LEVEL --- Zlib::MAX_MEM_LEVEL (()) 等に渡す、memory level を表す整数。 --- Zlib::MAX_WBITS (()) や (()) での ((|windowBits|)) のデフォルト値。 --- Zlib::NO_FLUSH --- Zlib::SYNC_FLUSH --- Zlib::FULL_FLUSH --- Zlib::FINISH (()) 等に渡す、ストリームの出力を制御するための整数。 --- 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::Error Ruby/zlib の発行する全ての例外のスーパークラス。以下の例外が Zlib::Error のサブクラスとして定義されています。それぞれ zlib ライブラリ関数の返すエラーと対応しています。 * Zlib::StreamEnd * Zlib::NeedDict * Zlib::DataError * Zlib::StreamError * Zlib::MemError * Zlib::BufError * Zlib::VersionError === スーパークラス: * StandardError == Zlib::ZStream 圧縮データを扱うストリームを表す抽象クラス。具体的な圧縮/展開の操作は、それぞれサブクラスの (()), (()) で定義されています。 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" 入力バッファの内容を処理している最中にエラーが発生した場合、 (()) のサブクラスの例外が発生します。その時、入力/出力バッファは共に、エラーが発生した時点の状態をそのまま保持します。 === スーパークラス: * Object === クラスメソッド: --- Zlib::ZStream.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::ZStream#adler alder-32 チェックサムを返します。 --- Zlib::ZStream#reset ストリームの状態をリセットします。入力/出力バッファ内に残っていたデータは破棄されます。 --- Zlib::ZStream#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|)) の有効な値は (()), (()), (()), (()) 及び 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 の場合はストリームへの入力を終了します。((()) と同じ)。 ((|flush|)) には (()), (()), (()), (()) のいずれかを指定します。詳しくは zlib.h を参照して下さい。 --- Zlib::Deflate#<< string (()) と同じように ((|string|)) を圧縮ストリームに入力しますが、Zlib::Deflate オブジェクトそのものを返します。圧縮ストリームからの出力は、出力バッファに保存されます。 --- Zlib::Deflate#flush([flush]) (({deflate('', ((|flush|)))})) と同じです。((|flush|)) が省略された時は (()) が使用されます。このメソッドはスクリプトの可読性のために提供されています。 --- Zlib::Deflate#finish 圧縮ストリームを終了します。(({deflate('', Zlib::FINISH)})) と同じです。 --- Zlib::Deflate#params(level, strategy) 圧縮ストリームの設定を変更します。詳しくは zlib.h を参照して下さい。設定の変更に伴うストリームからの出力は出力バッファに保存されます。 --- Zlib::Deflate#set_dictionary(string) 圧縮に用いる辞書を指定します。((|string|)) を返します。このメソッドは (()), (()) を呼び出した直後にのみ有効です。詳細は zlib.h を参照して下さい。 == Zlib::Inflate 入力データを展開するストリームのクラス。(()) と違い、このクラスのインスタンスを複製 (clone, dup) することはできません。 === スーパークラス: * (()) === クラスメソッド: --- Zlib::Inflate.inflate(string) ((|string|)) を展開します。展開に辞書が必要な場合には (()) 例外が発生します。ちなみに、このメソッドは以下のコードとほぼ同じです: 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::Inflate#<< string (()) と同じように ((|string|)) を展開ストリームに入力しますが、Zlib::Inflate オブジェクトそのものを返します。展開ストリームからの出力は、出力バッファに保存されます。 --- Zlib::Inflate#finish 展開ストリームを終了します。ストリーム内に残っていたデータ (つまり圧縮データの後についていたゴミデータ) を返します。 (()) が真でない時に finish を呼ぶと例外が発生します。展開ストリームは圧縮データ内に終了コードを発見した時点で自ら終了するため、明示的に finish を呼ぶ必要は必ずしもありませんが、このメソッドは圧縮データが正しく終了しているかを確認するのに便利です。 --- Zlib::Inflate#set_dictionary(string) 展開に用いる辞書を指定します。((|string|)) を返します。このメソッドは (()) 例外が発生した直後のみ有効です。詳細は 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 形式の圧縮ファイルを扱う抽象クラス。具体的な読み込み/書き込み操作は、それぞれサブクラスの (()), (()) で定義されています。 IO クラスのインスタンス (又は IO クラスのインスタンスと同じメソッドを持つオブジェクト) と関連付けて使用します。 === スーパークラス: * Object === クラスメソッド: --- Zlib::GzipFile.new(io) (()) 及び (()) を参照。 === メソッド: --- 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 === スーパークラス: * (()) === インクルードしているモジュール: * Enumerable === クラスメソッド: --- Zlib::GzipReader.new(io) --- Zlib::GzipReader.new(io) {|gz| ... } ((|io|)) と関連付けられた GzipReader オブジェクトを作成します。 GzipReader オブジェクトは ((|io|)) からデータを逐次リードして解析/展開を行います。((|io|)) には少なくとも、IO#read と同じ動作をする read メソッドが定義されている必要があります。ヘッダーの解析に失敗した場合 (()) 例外が発生します。ブロックを指定して呼び出した場合は、File.open と同じように GzipReader オブジェクトを与えられてブロックが実行されます。ブロックの実行が終了すると、GzipReader オブジェクトは自動的にクローズされます。関連付けられている IO オブジェクトまでクローズしたくない時は、ブロック中で引数つきの (()) メソッドを明示的に呼び出して下さい。 --- Zlib::GzipReader.open(filename) --- Zlib::GzipReader.open(filename) {|gz| ... } ((|filename|)) で指定されるファイルを gzip ファイルとしてオープンします。GzipReader オブジェクトを返します。その他詳細は (()) と同じです。 === メソッド: --- 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 ファイル中にエラーがあった場合 (()) 例外や (()) 例外が発生します。 gzip ファイルのフッターの処理に注意して下さい。 gzip ファイルのフッターには圧縮前データのチェックサムが記録されています。GzipReader オブジェクトは、次の時に展開したデータとフッターの照合を行い、エラーがあった場合は (()), (()), (()) 例外を発生させます。 * EOF (圧縮データの最後) を越えて読み込み要求を受けた時。すなわち (()), (()) メソッド等が nil を返す時。 * EOF まで読み込んだ後、(()) メソッドが呼び出された時。 * EOF まで読み込んだ後、(()) メソッドが呼び出された時。 --- Zlib::GzipReader#rewind ファイルポインタを (()) を呼び出した直後の時点に戻します。関連付けられている 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 オブジェクトは必ず (()) 等を用いてクローズしてください。そうしなければフッターを書き出すことができず、壊れた gzip ファイルを生成してしまう可能性があります。 === スーパークラス: * (()) === クラスメソッド: --- Zlib::GzipWriter.new(io[, level[, strategy]]) --- Zlib::GzipWriter.new(io[, level[, strategy]]) {|gz| ... } ((|io|)) と関連付けられた GzipWriter オブジェクトを作成します。 ((|level|)), ((|strategy|)) は (()) と同じです。 GzipWriter オブジェクトは ((|io|)) に gzip 形式のデータを逐次ライトします。((|io|)) には少なくとも、IO#write と同じ動作をする write メソッドが定義されている必要があります。ブロックを指定して呼び出した場合は、File.open と同じように GzipWriter オブジェクトを与えられてブロックが実行されます。ブロックの実行が終了すると、GzipWriter オブジェクトは自動的にクローズされます。関連付けられている IO オブジェクトまでクローズしたくない時は、ブロック中で引数つきの (()) メソッドを明示的に呼び出して下さい。 --- Zlib::GzipWriter.open(filename[, level[, strategy]]) --- Zlib::GzipWriter.open(filename[, level[, strategy]]) {|gz| ... } ((|filename|)) で指定されるファイルを gzip 圧縮データの書き出し用にオープンします。GzipWriter オブジェクトを返します。その他詳細は (()) と同じです。 === メソッド: --- 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|)) は (()) と同じです。省略時は (()) が使用されます。 ((|flush|)) に (()) を指定することは無意味です。 --- Zlib::GzipWriter#mtime= time gzip ファイルのヘッダーに記録する最終更新時間を指定します。 (()) 等の書き込み系メソッドを呼んだ後で指定しようとすると (()) 例外が発生します。 --- Zlib::GzipWriter#orig_name= filename gzip ファイルのヘッダーに記録する元ファイル名を指定します。 (()) 等の書き込み系メソッドを呼んだ後で指定しようとすると (()) 例外が発生します。 --- Zlib::GzipWriter#comment= string gzip ファイルのヘッダーに記録するコメントを指定します。 (()) 等の書き込み系メソッドを呼んだ後で指定しようとすると (()) 例外が発生します。 == 0.4.0 からの変更点全体的に書き換えてます。これで全部…だといいなぁ(汗:: * クラス名、メソッド名の変更。全てのクラスと定数は (()) 以下に移しました。0.4.0 との互換性のために以前のものも残してあります。 * クラス * Deflate -> (()) * Inflate -> (()) * Zlib::Gzip -> (()) * GzipReader -> (()) * GzipWriter -> (()) * Zlib::Gzip::Error -> (()) * Zlib::GzipReader::NoFooter -> (()) * Zlib::GzipReader::CRCError -> (()) * Zlib::GzipReader::LengthError -> (()) * 定数 * Zlib::ZStream::BINARY -> (()) * Zlib::ZStream::ASCII -> (()) * Zlib::ZStream::UNKNOWN -> (()) * Zlib::Deflate::NO_COMPRESSION -> (()) * Zlib::Deflate::BEST_SPEED -> (()) * Zlib::Deflate::BEST_COMPRESSION -> (()) * Zlib::Deflate::DEFAULT_COMPRESSION -> (()) * Zlib::Deflate::FILTERED -> (()) * Zlib::Deflate::HUFFMAN_ONLY -> (()) * Zlib::Deflate::DEFAULT_STRATEGY -> (()) * Zlib::Deflate::MAX_WBITS -> (()) * Zlib::Deflate::DEF_MEM_LEVEL -> (()) * Zlib::Deflate::MAX_MEM_LEVEL -> (()) * Zlib::Deflate::NO_FLUSH -> (()) * Zlib::Deflate::SYNC_FLUSH -> (()) * Zlib::Deflate::FULL_FLUSH -> (()) * Zlib::Inflate::MAX_WBITS -> (()) * Zlib::GzipReader::OS_* -> (()) * メソッド * Zlib::ZStream#flush_out -> (()) * (()) の追加。 * 入力側 (next_in) にもバッファを設ける。 * NeedDict エラーは特別に処理するようにした。 * (()) はクローズ後は nil を返す。 * (()) の義務化。finalizer での segv を回避。 ((<[ruby-dev:11915]|URL:http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-dev/11915>)) * new と initialize を分けた。 * deflateInit2, inflateInit2 に渡す引数の sanity check をしないようにした。 * (()) の挙動は Ruby-1.7 に合わせることにした。 * 全関数を static に。 =end